Ошибки
Каждый эндпоинт завершается одинаково: HTTP-статусом и одним JSON-конвертом.
{
"error": {
"type": "invalid_request",
"code": "invalid_input",
"message": "duration must be one of 5, 10.",
"param": "duration",
"details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ],
"request_id": null,
"doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
}
}| Поле | Значение |
|---|---|
type |
Общий класс ошибки. По нему определяется дальнейшее действие. |
code |
Точная причина, стабильная и машиночитаемая. Для каждого кода ниже есть отдельный раздел; doc_url ведёт на него. |
message |
Понятное человеку объяснение, безопасное для записи в журнал или показа разработчику. |
param |
Проблемный входной параметр или заголовок, если он есть. |
details |
Для ошибок входных данных — все найденные проблемы: [{ "param", "message" }]. |
request_id |
Запрос, к которому относится ошибка, если он существует. |
За вызов, вернувший ошибку, плата не взимается. Запрос, завершившийся ошибкой после принятия, сохраняет статус
failed, содержит error: { "type", "code", "message" } в объекте запроса и автоматически возвращается.
Типы
| Тип | HTTP-статус | Действие |
|---|---|---|
invalid_request |
400, 413 или 422 | Исправьте запрос. Повторная отправка того же вызова снова завершится ошибкой. |
authentication_error |
401 | Передайте действительный ключ в Authorization: Bearer <key>. |
permission_error |
403 | Используйте ключ с необходимой областью доступа. |
not_found |
404 | Проверьте идентификатор модели или запроса. |
insufficient_credits |
402 | Пополните баланс API (top_up_url в ошибке). |
budget_exceeded |
402 | Собственный бюджет ключа исчерпан. Окончательное решение: попросите владельца ключа увеличить его. |
conflict |
409 | Ресурс находится в состоянии, не допускающем этот вызов. |
rate_limited |
429 | Подождите Retry-After секунд, затем повторите запрос. |
upstream_error |
502 | Сервер модели завершился с ошибкой. Безопасно повторить с тем же Idempotency-Key: операция запустится снова, плата не взималась. |
service_unavailable |
503 | API приостановлен или недоступна зависимость. Повторите позже. |
internal_error |
500 | Ошибка на нашей стороне. Повторите запрос; если ошибка сохраняется, обратитесь в поддержку, указав время и request_id. |
Коды
invalid_request
Общий некорректно сформированный запрос (400).
invalid_json
Тело не является допустимым JSON (400).
invalid_body
Тело является допустимым JSON, но не объектом; входные данные модели должны быть JSON-объектом (400).
body_too_large
Тело больше 16 MB (413). Загрузите большие файлы и передайте вместо них URL (см. Файлы).
invalid_parameter
Параметр запроса содержит недопустимое значение: например, limit вне диапазона от 1 до 100, wait не является числом, неизвестны
status или category, либо storage отличается от permanent / temporary (400). Имя параметра указано в param.
invalid_category
GET /openapi.json?category= указывает несуществующую категорию (400). Запрос GET https://api.doitong.com/v1/categories выводит их список.
invalid_cursor
cursor вызова списка не относится к этому списку (400). Начните заново без курсора.
invalid_idempotency_key
Заголовок Idempotency-Key пуст или содержит более 255 символов (400).
invalid_arguments
Вызову инструмента MCP не хватает аргумента или он некорректно сформирован (только MCP). Имя аргумента указано в param.
invalid_input
Входные данные модели не прошли проверку (422): неизвестный параметр (сообщение предлагает ближайшее допустимое имя),
отсутствующий обязательный параметр, неверный тип, значение вне разрешённого списка или диапазона либо одновременно
указанные каноническое и нативное имена с разными значениями. param содержит первый проблемный параметр, а details — все такие параметры.
Плата не взимается.
unsupported_file
Файл имеет неподдерживаемый тип (422): например, загружен файл с неподдерживаемым расширением или content_type,
не соответствующий расширению.
invalid_webhook_url
webhook_url не является общедоступным URL https:// (422). Приватные, локальные и обычные адреса http:// отклоняются.
missing_api_key
Эндпоинту требуется API-ключ, но он не был передан (401).
invalid_api_key
Ключ неизвестен, отозван или просрочен (401).
insufficient_scope
У ключа нет области доступа, необходимой для вызова (403): например, models:run для запуска или models:read для чтения
запросов и баланса. См. Аутентификация.
account_disabled
Аккаунт закрыт или заблокирован (403). Его ключи больше не работают.
not_found
Путь не существует (404).
model_not_found
Общедоступной модели с таким идентификатором нет (404). Получите список моделей с помощью GET https://api.doitong.com/v1/models.
request_not_found
В вашем аккаунте нет запроса с таким идентификатором (404). Запросы других аккаунтов никогда не видны.
insufficient_credits
API-баланса аккаунта (API-кредиты, 1 000 API-кредитов = 1 $ — не кредиты приложений Doitong) недостаточно для оплаты
этого вызова (402). Ответ отправляется до списания средств. Ошибка содержит top_up_url; пополните баланс по адресу
https://doitong.com/developers/dashboard#balance и повторите запрос.
{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
"message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.com/developers/dashboard#balance",
"top_up_url": "https://doitong.com/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }budget_exceeded
Вызов превысил бы собственный бюджет API-ключа в API-кредитах (402). Бюджет устанавливает владелец ключа; повторная отправка не поможет, пока он не увеличит бюджет.
conflict
Вызов конфликтует с текущим состоянием ресурса (409).
idempotency_mismatch
Idempotency-Key уже использовался с другим телом запроса (409). Для новой операции используйте новый ключ.
idempotency_in_progress
Прямо сейчас создаётся запрос с тем же Idempotency-Key (409). Повторите через мгновение, чтобы получить его.
request_active
Запрос всё ещё имеет статус queued или running, поэтому удалять пока нечего (409). Удалите файлы после завершения запроса.
not_cancelable
Запрос уже имеет статус succeeded или failed и не может быть отменён (409).
rate_limited
Ключ отправил слишком много запросов за текущий период (429). См. заголовки X-RateLimit-* и Retry-After.
too_many_inflight
В аккаунте уже есть 10 запросов со статусом queued или running (429). Запустите следующий после завершения одного из них.
upstream_error
Сервер модели отклонил запрос или завершился с ошибкой (502 при запуске либо failed с этим кодом у запроса). API-кредиты
возвращаются. Если сервер модели сам отклонил входные данные, вызов возвращает 422 invalid_input с соответствующим сообщением.
upstream_lost
Сервер модели больше не знает об этом запросе, поэтому результат никогда не будет получен. Запрос завершается со статусом failed
и этим кодом (тип upstream_error), а средства возвращаются. Запустите его снова.
timeout
Запрос выполнялся дольше установленного ограничения (15 минут для изображений, 60 для видео, 30 в остальных случаях) и был остановлен.
Он завершается со статусом failed с этим кодом, а средства возвращаются.
service_unavailable
API временно приостановлен или недоступна зависимость, например загрузка файлов (503). Повторите позже.
internal_error
На нашей стороне произошла ошибка (500). Повторите запрос; если ошибка сохраняется, обратитесь в поддержку.
charge_failed
С аккаунта не удалось списать средства из-за внутренней проблемы (500). Запрос получает статус failed; средства не списываются.
Повторите запрос.
pricing_unavailable
Цена модели не настроена, поэтому сейчас её нельзя узнать или запустить модель (500).