Документация для разработчиковНачало работы
Ошибки
Единый формат ошибок, стабильные коды, понятные правила повтора.
Все ответы с кодом, отличным от 2xx, имеют одинаковую структуру. Ветвите логику по error.code, а не по message.
{
"error": {
"code": "validation_failed",
"message": "The request is invalid.",
"request_id": "req_8fK2Lq9ZtX4mN7bV1cW3yH6p",
"details": [
{
"path": "items[3].length",
"code": "out_of_range",
"message": "length must be greater than 0."
}
]
}
}| Поле | Содержимое |
|---|---|
code | Стабильный, в snake_case |
message | На английском, для логов |
request_id | Также в X-Request-Id. Сообщайте его в поддержку |
details[] | При 400/422: path, code, message для каждой проблемы |
Коды
| Статус | Код | Значение | Что делать | Можно повторить |
|---|---|---|---|---|
| 400 | invalid_json | Тело запроса — невалидный JSON, или у поля неверный тип. | Исправьте тело запроса. | Нет |
| 401 | unauthorized | API-ключ отсутствует, имеет неверный формат или неизвестен. | Передавайте заголовок Authorization: Bearer cd_live_…; проверьте, что ключ скопирован целиком. | Нет |
| 401 | key_revoked | Ключ отозван. | Создайте новый ключ в консоли разработчика. | Нет |
| 401 | key_expired | Срок действия ключа истёк. | Создайте новый ключ в консоли разработчика. | Нет |
| 402 | insufficient_credits | Доступных кредитов не хватает даже на минимально возможный расчёт этого задания. | Купите пакет кредитов или дождитесь ежемесячного начисления; ничего не списано. | Нет |
| 403 | ip_not_allowed | IP-адреса вызывающей стороны нет в списке разрешённых IP для этого ключа. | Вызывайте API с разрешённого IP-адреса или измените список разрешённых IP. | Нет |
| 403 | subscription_inactive | У организации нет активной подписки, включающей API. | Продлите подписку. | Нет |
| 403 | account_inactive | Работа организации приостановлена, или у неё нет владельца с активной учётной записью. | Обратитесь в поддержку. | Нет |
| 403 | scope_missing | У ключа нет области доступа, необходимой для этого endpoint. | Используйте ключ с нужной областью доступа (pack:write, jobs:read, account:read, resources:read, resources:write). | Нет |
| 403 | preset_read_only | Пресеты нельзя изменять или удалять. | Создайте собственное транспортное средство через POST /v1/vehicles. | Нет |
| 403 | plan_limit_reached | Тариф организации не позволяет создать больше проектов или позиций груза. | Удалите ненужные проекты или перейдите на тариф с более высокими лимитами. | Нет |
| 404 | not_found | Endpoint /v1 с таким методом и путём не существует. | Сверьте метод и путь со справочником API. | Нет |
| 404 | job_not_found | В вашей организации нет задания с таким ID. | Проверьте ID. | Нет |
| 404 | vehicle_not_found | Транспортного средства с таким ID нет ни среди пресетов, ни среди транспортных средств вашей организации. | Сверьте ID со списком GET /v1/vehicles. | Нет |
| 404 | template_not_found | В вашей организации нет шаблона с таким ID. | Сверьте ID со списком GET /v1/templates. | Нет |
| 404 | project_not_found | В вашей организации нет проекта с таким ID. | Сверьте ID со списком GET /v1/projects. | Нет |
| 409 | job_not_finished | Задание ещё в очереди или выполняется. | Опрашивайте GET /v1/jobs/{id}, пока status не станет succeeded. | Да |
| 409 | project_busy | Загрузка проекта прямо сейчас рассчитывается (в приложении или другим заданием). | Дождитесь окончания этого расчёта и повторите. | Да |
| 409 | job_failed | Задание завершилось ошибкой; результата нет. | Смотрите job.error; сбои на нашей стороне не оплачиваются (time_limit_exceeded оплачивается как отменённое задание). Если причина была временной, отправьте задание заново. | Нет |
| 409 | job_canceled | Задание отменено; результата нет. | При необходимости отправьте задание заново. | Нет |
| 409 | job_already_finished | Задание уже завершено, отменить его нельзя. | Ничего делать не нужно. | Нет |
| 400 | idempotency_key_invalid | Длина заголовка Idempotency-Key превышает 128 симв. | Используйте ключ покороче (подойдёт UUID). | Нет |
| 410 | result_expired | Срок хранения результата истёк, и он удалён. | Если план снова нужен, отправьте задание заново. | Нет |
| 413 | payload_too_large | Тело запроса превышает 10 MB. | Отправьте меньше позиций или упростите их. | Нет |
| 422 | validation_failed | Запрос — корректный JSON, но описывает недопустимое задание. В details[] перечислены все проблемы. | Исправьте все поля, указанные в details[].path; ошибки валидации бесплатны. | Нет |
| 429 | rate_limited | Слишком много запросов за текущую минуту, час или сутки (на ключ или на организацию) либо число неудачных попыток аутентификации с вашего IP-адреса превысило 60 в минуту. | Подождите столько секунд, сколько указано в Retry-After, затем повторите запрос с экспоненциальной задержкой. | Да |
| 429 | too_many_jobs | У организации уже максимальное число заданий в очереди и в работе. | Дождитесь завершения выполняющихся заданий и повторите. | Да |
| 500 | internal_error | Сбой на нашей стороне. | Повторите запрос с экспоненциальной задержкой; если ошибка повторяется, сообщите в поддержку request_id. | Да |
| 503 | api_disabled | API временно отключён (техническое обслуживание) или выключен для организации. | Повторите позже. | Да |
Детали валидации
details[].code в ответе 422 validation_failed:
| Код | Значение |
|---|---|
required | Не передано обязательное поле |
invalid_value | Неверный тип или недопустимое значение |
out_of_range | Значение слишком маленькое, слишком большое или слишком длинное |
duplicate_id | ID используется дважды |
unknown_vehicle | Нет ни пресета, ни вашего транспортного средства с таким vehicle_id |
unknown_template | У вас нет шаблона с таким template_id |
type_not_allowed | Тип транспортного средства не включён для вашей организации |
unknown_group | Позиция ссылается на группу, которой нет в списке |
does_not_fit | Позиция не помещается ни в одно из указанных транспортных средств |
too_many_items | Единиц груза больше лимита задания |
too_many_vehicles | Транспортных средств больше лимита задания |
unknown_field | Поле, неизвестное API |
Ошибки заданий
Задание в статусе failed или canceled указывает причину в job.error.code:
| Код | Значение |
|---|---|
canceled | Отменено через DELETE /v1/jobs/{id}. Списываются плата за задание и стоимость использованных вычислений. |
time_limit_exceeded | Бюджет времени вычислений исчерпан раньше, чем было загружено хотя бы одно транспортное средство. Оплачивается как отменённое задание: плата за задание, надбавка за крупную загрузку и использованные вычисления; плата за транспортные средства не взимается. |
engine_failed | Сбой алгоритма загрузки. Не оплачивается. |
queue_timeout | Задание слишком долго ждало свободного слота вычислений. Не оплачивается. |
server_restarted | Сервис перезапустился, пока задание ждало в очереди или выполнялось. Не оплачивается. |
Повторы
Повторяйте запросы, получившие 429, 500 и 503, с экспоненциальной задержкой и с учётом Retry-After. Передавайте тот же Idempotency-Key (Идемпотентность). Запросы с другими ошибками 4xx не повторяйте без изменений.