Руководства
Ошибки
Формат ошибок, коды статуса и какие ошибки стоит повторять.
Ошибки приходят в формате того эндпоинта, который вы вызвали.
Форматы OpenAI:
{"error": {"message": "not enough credits for this request. Add credits in the console", "type": "insufficient_quota", "code": "insufficient_credits", "param": null, "request_id": "req_..."}}Messages:
{"type": "error", "error": {"type": "rate_limit_error", "message": "too many requests per minute for this key"}, "request_id": "req_..."}| Статус | Код | Повторять? | Что делать |
|---|---|---|---|
| 400 | invalid_request, unsupported_parameter | Нет | Исправьте тело запроса |
| 400 | context_length_exceeded | После сокращения | См. Длина контекста |
| 401 | invalid_api_key | Нет | Проверьте ключ |
| 402 | insufficient_credits, key_budget_exceeded | Нет | Пополните баланс или увеличьте бюджет ключа |
| 403 | key_not_allowed, account_suspended | Нет | Проверьте модели и разрешённые IP ключа или напишите в поддержку |
| 403 | consent_required | Нет | Создатель ключа не дал или отозвал согласие на обработку партнёрами в других странах. Принять его можно в консоли |
| 404 | model_not_found, not_found | Нет | Проверьте ID |
| 413 | request_too_large | Нет | Отправляйте меньше |
| 429 | rate_limit_exceeded, concurrency_limit_exceeded, capacity_busy | Да | Подождите retry-after секунд |
| 500 | internal_error | Да, с задержкой | Если повторяется, сообщите x-request-id |
| 502, 504 | upstream_error, upstream_timeout | Да, с задержкой | |
| 503 | model_unavailable | Да | Повторите с задержкой (retry-after задаётся, пока сервис перезапускается) или используйте другую модель |
retry-after указывается в целых секундах, не больше 60.
Запрос, который упал до начала ответа, не оплачивается, а в разделе Активность он виден со статусом и кодом ошибки (до 30 упавших запросов на ключ в минуту). Если ответ оборвался на середине, вы платите за уже сгенерированные токены.
Длина контекста
Запрос, который не помещается в модель, возвращает 400. В форматах OpenAI код ошибки context_length_exceeded. В Messages тип invalid_request_error, сообщение то же. Если уже по оценке запрос намного больше лимита, он останавливается до обращения к модели:
this request has about N tokens and MODEL accepts M; shorten it or compact the conversationИначе его отклоняет сама модель, обычно потому, что промпт вместе с лимитом вывода не помещается, и сообщение такое:
this request is too large for MODEL, which accepts M tokens including the answer; shorten it or compact the conversationВ обоих случаях оплаты нет. N — это оценка. Лимит каждой модели указан как context_length в GET /v1/models.
API не сжимает переписку. Как и другие API, совместимые с OpenAI и Anthropic, он никогда не отбрасывает и не переписывает ваши сообщения, поэтому держать переписку в пределах лимита должен клиент. Удалите самые старые сообщения или замените их сводкой, не разделяйте вызов инструмента и его результаты и отправьте запрос снова. Агент в терминале делает это за вас.
Безопасные повторы
Для запросов без стриминга отправляйте заголовок Idempotency-Key. Повтор с тем же ключом в течение 24 часов возвращает первый ответ с x-notholy-idempotent-replay: true и повторно не оплачивается. Воспроизводятся только успешные ответы. Ответ хранится в памяти сервера, который его дал, и никогда на диске, поэтому повтор после перезапуска или на другом сервере выполняется заново и оплачивается.
curl https://api.notholy.com/v1/chat/completions \
-H "Authorization: Bearer $NOTHOLY_API_KEY" \
-H "Idempotency-Key: report-42-summary" \
-H "Content-Type: application/json" \
-d '{"model": "notholy-specter", "messages": [{"role": "user", "content": "One-line summary of an open redirect."}]}'Официальные SDK уже повторяют 429 и 5xx с задержкой.