Ошибки
Любой отказ приходит в формате 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 | да | Внутренняя ошибка |