API

Ошибки

Любой отказ приходит в формате RFC 9457 application/problem+json — и те, что случаются ещё до контроллера. HTML-страницы с ошибкой вы не получите никогда.

{
  "type": "…/errors/insufficient_tokens",
  "code": "insufficient_tokens",
  "status": 402,
  "title": "Not enough tokens",
  "detail": "This run costs 750 tokens.",
  "hint": "Top up with POST /v1/billing/topup_link, then retry.",
  "retryable": false,
  "required_tokens": 750,
  "available_tokens": 120,
  "docs_url": "…/errors/insufficient_tokens",
  "request_id": "req_01J…"
}
Ветвитесь по code, а не по detail: код — контракт, текст — нет. retryable говорит, может ли повтор вообще помочь. Повторять 402 без конца — только сжигать лимит частоты, а сдаться на 503 — бросить задачу, которую можно было довести. hint подсказывает, что делать, а request_id нужен поддержке.
КодHTTPПовтор поможетЗначение
invalid_key 401 нет Неверный ключ API
key_revoked 401 нет Ключ API удалён
key_expired 401 нет Срок ключа API истёк
key_disabled 403 нет Ключ API приостановлен владельцем
key_read_only 403 нет Ключ API только для чтения
key_suspended 403 нет Ключ API остановлен
fetch_quota_exceeded 429 да Исчерпан лимит скачивания по адресу
missing_key 401 нет Нет ключа API
ip_not_allowed 403 нет Этому ключу нельзя с этого IP
tool_not_allowed 403 нет Этому ключу нельзя этот тул
email_not_verified 403 нет Почта не подтверждена
plan_required 403 нет Аккаунту не открыт доступ к API
unknown_tool 404 нет Неизвестный тул
unknown_run 404 нет Неизвестный запуск
unknown_lane 404 нет У тула нет такой полосы
wrong_shard 421 нет Ключ от другого домена API
wrong_audience 401 нет Токен не для этого адреса
validation_failed 422 нет Неверный вход
insufficient_tokens 402 нет Не хватает токенов
idempotency_conflict 409 нет Ключ идемпотентности уже занят другим запросом
run_not_cancellable 409 нет Запуск уже завершён
input_too_large 413 нет Слишком большой вход
too_long 422 нет Слишком длинная запись
rate_limited 429 да Превышен лимит частоты
concurrency_limited 429 да Слишком много запусков одновременно
tool_unavailable 503 да Тул временно недоступен
upstream_unavailable 503 да Внешний сервис временно недоступен
api_disabled 503 да API выключен
internal_error 500 да Внутренняя ошибка