Ошибки

Для каждого сбоя BeatAPI возвращает один из фиксированных кодов. Ветвите логику по code или retryable; поле message содержит английское описание причины для человека. BeatAPI не раскрывает поставщика модели и не передаёт его исходные ответы. Единственное исключение — английское сообщение модели о неверных входных данных в текстовом API: оно передаётся, чтобы вы могли исправить запрос. Сохраняйте request_id для поддержки.

Объект ошибки

Все методы BeatAPI — задачи изображений и видео, GET /v1/tasks/{task_id}, возможности, рабочие процессы, /v1/systemone и его псевдоним /v1/decisions, /v1/moderations, /v1/social-data/call и /v1/web/* — используют единый объект ошибки:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: at most 60 successful requests per 1 minute(s). Retry after 60 seconds.",
    "retryable": true,
    "request_id": "req_abc123",
    "retry_after_seconds": 60
  }
}

Методы POST /v1/chat/completions, POST /v1/responses и POST /v1/messages используют этот объект для ошибок до вызова модели, а во время вызова сохраняют формат ошибок своего SDK. См. текстовый API. Исходные методы Gemini (/v1beta/...) и GET /v1/models используют другой, более простой формат; он описан там же.

POST /v1/moderations также использует этот объект. Дополнительно в нём есть поля OpenAI type и param, причём param всегда равен null. Это позволяет OpenAI SDK создавать обычные для него исключения. См. Moderation API.

Где искать ошибку

Задача может завершиться ошибкой на двух этапах, и ответы будут различаться:

1. При создании. Запрос отклонён до появления задачи. Возвращается HTTP-ошибка с объектом error, без data.id. Средства не списываются.
2. После принятия. POST вернул 201 с data.id, но позже задача завершилась со status: "failed". Метод GET /v1/tasks/{task_id} по-прежнему возвращает 200; ошибка указана в data.error_code, data.error_message и data.retryable. Зарезервированные средства возвращаются.

{
  "error": {
    "code": "content_policy_violation",
    "message": "The request was blocked by content moderation. Please change the prompt or the input and try again.",
    "retryable": false,
    "request_id": "req_abc123"
  }
}

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "status": "failed",
    "error_code": "content_policy_violation",
    "error_message": "The request was blocked by content moderation. Please change the prompt or the input and try again.",
    "retryable": false
  }
}

Одна причина имеет один код на обоих этапах и в строке ошибки журнала использования (content_policy_violation: The request was blocked…). Неудачная задача не является HTTP-ошибкой: GET /v1/tasks/{task_id} возвращает 200 со status: "failed", error_code, error_message и retryable, а резерв возвращается. Поле usage.credits_reserved показывает сумму при создании; usage.credits_charged и usage.credits_settled равны 0; usage.credits_refunded содержит сумму возврата.

Уже принятая задача может завершиться только одним из следующих шести кодов. Остальные коды означают отказ на этапе запроса.

Если задачу завершил обработчик тайм-аутов, событие вебхука не отправляется. Поэтому продолжайте проверять GET /v1/tasks/{task_id}: статус задачи остаётся источником истины.

Вызовы возможностей

Отложенный вызов возможности при ошибке возвращает стандартный объект выше: code, message, retryable и request_id. HTTP-статус определяется кодом, например 503 для processing_*. Такой вызов не оплачивается. Если выполнение продолжается дольше примерно 85 секунд, возвращается 202 со status: "running".

POST /v1/capabilities/run с operation: "result" читает сохранённый результат по request_id. Результаты хранятся один час. Если результата нет, возвращается 404 result_expired с retryable: false; выполните возможность заново.

Коды

Слишком большое тело запроса в API изображений и видео даёт 400 bad_request с сообщением «Request body is too large.». Код 413 read_request_body_failed есть только в текстовом API и не включён в таблицу: у него нет поля retryable. Повтор без изменений бессмысленен; уменьшите тело. Подробности ниже.

processing_unavailable и rate_limit_exceeded — разные причины. rate_limit_exceeded относится к вашей частоте запросов и требует замедления. processing_unavailable означает, что модель сейчас не может принять работу, хотя ваши запросы допустимы.

BeatAPI не возвращает 502 или 504. Такие 502 и 504 приходят с сетевого уровня, когда BeatAPI недоступен; тело не является JSON. Повторяйте с увеличением задержки, как 503. Аналогично 403 с телом error code: 1010: сетевой уровень отклонил стандартный User-Agent клиента, например Python urllib. Явно задайте User-Agent.

Коды Realtime

Они встречаются только в сессиях Realtime. Подпись вебхука проверяет ваш обработчик, поэтому BeatAPI не возвращает отдельный код для её проверки. См. вебхуки.

Текстовый API

В POST /v1/chat/completions, POST /v1/responses и POST /v1/messages ошибки могут возникнуть на двух этапах, с разными форматами ответа.

1. До вызова модели. Ошибки отсутствующего или неверного ключа, доступа за бонус, разрешённых IP, группы ключа, маршрутизации и частоты запросов используют объект BeatAPI: code, message, retryable, request_id, а при 429 также retry_after_seconds и Retry-After. Неизвестная модель даёт 404 not_found. IP вне списка или модель вне группы ключа дают 403 forbidden. Это относится к /v1/chat/completions, /v1/responses и /v1/messages.

Исходные методы Gemini и GET /v1/models. /v1beta/... и GET /v1/models не используют объект BeatAPI. Ошибка имеет вид {"error":{"message":"... (request id: ...)","type":"beatapi_error","code":...}}, без retryable и retry_after_seconds. При 429 заголовок Retry-After всё равно присутствует.

2. Во время вызова. Намеренно сохраняется формат соответствующего SDK, чтобы OpenAI и Anthropic SDK создавали обычные исключения. Поля retryable нет; ориентируйтесь на статус и код. На этом этапе ID запроса добавляется к каждому message. Возможны три вида ошибок:

• Отказ самого шлюза использует код BeatAPI: insufficient_credits, content_policy_violation, bad_request, not_found или internal_error.
• Ошибка на стороне модели преобразуется в формат SDK с кодом temporary_error, upstream_timeout, model_unavailable или rate_limit_exceeded. HTTP-статус сохраняется, кроме преобразования 502 и 504 в 503. Проблема аккаунта сервиса у поставщика возвращается как 503 model_unavailable.
• Английское сообщение модели о неверном параметре, например слишком длинном контексте, передаётся, чтобы вы могли исправить входные данные.

Формат OpenAI (/v1/chat/completions, /v1/responses):

{
  "error": {
    "message": "This API key's remaining quota is below the price of this request. Raise the key's quota in the console or use another key. (request id: req_abc123)",
    "type": "beatapi_error",
    "param": "",
    "code": "insufficient_credits"
  }
}

Формат Anthropic (/v1/messages):

{
  "type": "error",
  "error": {
    "type": "insufficient_credits",
    "message": "This API key's remaining quota is below the price of this request. Raise the key's quota in the console or use another key. (request id: req_abc123)"
  }
}

При отказе самого шлюза поле type в формате OpenAI равно beatapi_error, код BeatAPI находится в error.code. В формате Anthropic код находится в error.type.

Правила повторных попыток

• Не повторяйте без изменений (retryable: false): bad_request, content_policy_violation, missing_api_key, invalid_api_key, unauthorized, insufficient_credits, forbidden, not_found, result_expired, read_request_body_failed, idempotency_conflict, not_implemented, realtime_session_expired, то есть все 400, 401, 402, 403, 404, 409, 410, 413 и 501. У read_request_body_failed нет retryable, и он не включён в таблицу кодов; обрабатывайте его как false.
• Повторяйте после ожидания (retryable: true): rate_limit_exceeded. Соблюдайте Retry-After / retry_after_seconds.
• Повторяйте с увеличением задержки (retryable: true): internal_error и четыре кода 503 — processing_unavailable, processing_timeout, processing_failed, result_transfer_failed. Коды Realtime 503 отличаются: realtime_capacity_unavailable допускает повтор, realtime_disabled — нет. Используйте экспоненциальную задержку со случайным разбросом и пределом. Средства за неудачную задачу возвращены: новая попытка оплачивается только при успехе. Передавайте Idempotency-Key при создании, чтобы повтор запроса не создал вторую задачу.

Идемпотентность

Idempotency-Key необязателен при создании задач и в POST /v1/capabilities/run.

• Ключ хранится 24 часа.
• Ключ длиннее 255 символов даёт 400 bad_request.
• Тот же ключ с другим телом или путём даёт 409 idempotency_conflict. Такой же ответ возможен, пока первый запрос ещё выполняется.
• Повтор идентичного запроса возвращает сохранённый ответ с заголовком Idempotent-Replayed: true.
• Сохраняются только ответы 2xx. После 400 или 402 можно повторить запрос с тем же ключом.

Результаты

URL результатов возвращаются в output.media[].url. Скачайте и сохраните всё, что нужно хранить постоянно.

Изменения

• 2026-10-15: при невозможности сохранить загружаемый файл возвращается 503 (processing_unavailable или result_transfer_failed), ничего не сохраняется. Во время текстового вызова ошибка модели преобразуется в формат SDK с temporary_error, upstream_timeout, model_unavailable или rate_limit_exceeded. ID запроса добавляется к каждому сообщению этого этапа.
• 2026-10-15: неудачный отложенный вызов возможности теперь возвращает стандартный объект (code, message, retryable, request_id) и HTTP-статус своего кода, а не type: api_error. retry_after_seconds и Retry-After передаются только при 429 rate_limit_exceeded, не при 503. Добавлены result_expired и not_implemented. Удалены user_concurrency_exceeded и invalid_signature: шлюз никогда их не возвращал. При ошибке задачи usage.credits_charged равен 0, а usage.credits_refunded показывает возврат. Текстовые ошибки до модели используют объект BeatAPI, во время вызова — формат SDK.
• 2026-09-29: 401 всегда означает missing_api_key, если ключ отсутствует, либо invalid_api_key, если ключ неверен, просрочен, отключён или исчерпан; сообщение уточняет причину. unauthorized — прежнее имя обоих случаев; старые ответы обрабатывайте как invalid_api_key. Недостаточный баланс всегда даёт 402 insufficient_credits во всех API, включая текстовый. Каждая ошибка содержит retryable, а каждое message — английское описание причины.
• 2026-09-25: BeatAPI больше не возвращает 502 или 504. Все ошибки обработки (processing_unavailable, processing_timeout, processing_failed, result_transfer_failed) дают 503 со стандартным JSON, включая неудачные синхронные вызовы соцсетей и веба и неудачное фоновое исследование с возвратом средств. Если вы видите 502, ответ пришёл с сетевого уровня при недоступном BeatAPI; тело не JSON. Повторяйте с увеличением задержки.
• 2026-09-23: если принятая задача не выполнилась из-за отклонённого параметра или недоступного входа, она сообщает bad_request вместо processing_failed. HTTP-статус самой модели больше не передаётся при создании: отказ модерации всегда 400 content_policy_violation, недоступная модель — 503 processing_unavailable. Недостаточный баланс при создании даёт 402 insufficient_credits.