> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # Ошибки > Все коды ошибок BeatAPI: HTTP-статусы, признак retryable, условия возникновения и действия клиента. # Ошибки Для каждого сбоя 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/*` — используют единый объект ошибки: ```json { "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 } } ``` | Поле | Когда присутствует | Значение | | --------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | Всегда | Код из таблицы ниже. Используйте его в логике обработки. | | `message` | Всегда | Английское описание причины; при `bad_request` называет поле. Предназначено для человека и журналов, не разбирайте его программно. | | `retryable` | Для каждого кода из таблицы ниже | `true`, если тот же вызов может сработать позже: все коды `429`, `500` и `503` из таблицы. `false`, если без изменения запроса, ключа или баланса ошибка повторится. Никогда не повторяйте бесконечно вызов с `retryable`, равным `false`. Поле может отсутствовать только у кода, которого нет в таблице. | | `request_id` | Всегда | Сохраните ID: по нему поддержка найдёт вызов. | | `retry_after_seconds` | Только при `429 rate_limit_exceeded` | Число секунд ожидания. То же значение передаётся в заголовке `Retry-After`. У других кодов поля нет: при `503` точное время ожидания неизвестно, поэтому увеличивайте задержку между попытками. | Методы `POST /v1/chat/completions`, `POST /v1/responses` и `POST /v1/messages` используют этот объект для ошибок до вызова модели, а во время вызова сохраняют формат ошибок своего SDK. См. [текстовый API](#text-endpoints). Исходные методы Gemini (`/v1beta/...`) и `GET /v1/models` используют другой, более простой формат; он описан там же. `POST /v1/moderations` также использует этот объект. Дополнительно в нём есть поля OpenAI `type` и `param`, причём `param` всегда равен `null`. Это позволяет OpenAI SDK создавать обычные для него исключения. См. [Moderation API](/moderation). ## Где искать ошибку Задача может завершиться ошибкой на двух этапах, и ответы будут различаться: 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`. Зарезервированные средства возвращаются. ```json { "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" } } ``` ```json { "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` содержит сумму возврата. Уже принятая задача может завершиться только одним из следующих шести кодов. Остальные коды означают отказ на этапе запроса. | `error_code` | Значение | `retryable` | | -------------------------- | ------------------------------------------------------------------ | ----------- | | `content_policy_violation` | Промпт, входные данные или результат отклонены модерацией. | `false` | | `bad_request` | Модель отклонила параметр или входные данные не удалось загрузить. | `false` | | `processing_unavailable` | Модель недоступна или перегружена. | `true` | | `processing_timeout` | Задача не завершилась в отведённое время и была остановлена. | `true` | | `processing_failed` | Обработка завершилась по другой причине на стороне сервиса. | `true` | | `result_transfer_failed` | Результат сгенерирован, но сохранить его не удалось. | `true` | Если задачу завершил обработчик тайм-аутов, событие [вебхука](/webhooks) не отправляется. Поэтому продолжайте проверять `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`; выполните возможность заново. ## Коды | Код | HTTP | `retryable` | Когда возникает | Что делать | | -------------------------- | ----- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `bad_request` | `400` | `false` | Некорректный JSON, неподдерживаемое поле, значение или сочетание: размер, пропорции, длительность, количество, длина промпта и другое. Сообщение называет поле. Также возникает при недоступном входном URL или файле, который нельзя обработать. | Исправьте поле либо используйте общедоступный HTTPS URL и поддерживаемый формат. | | `content_policy_violation` | `400` | `false` | Промпт, входные данные или сгенерированный результат отклонены модерацией. | Измените промпт или вход. Не отправляйте тот же запрос без изменений. | | `missing_api_key` | `401` | `false` | API-ключ не передан. | Добавьте `Authorization: Bearer `. Ключ работает с префиксом `sk-` и без него. | | `invalid_api_key` | `401` | `false` | Ключ неверен, просрочен, отключён или его лимит исчерпан; причина указана в сообщении. Удалённый ключ перестаёт работать немедленно. | Проверьте активный ключ в панели управления или используйте другой. | | `unauthorized` | `401` | `false` | Прежний код `401`, заменённый на `missing_api_key` и `invalid_api_key` 29 сентября 2026 года. Иногда ещё встречается. | Обрабатывайте как `invalid_api_key`. | | `insufficient_credits` | `402` | `false` | Баланс аккаунта равен нулю или меньше цены запроса либо недостаточен собственный лимит расходов ключа; это указано в сообщении. | Пополните баланс или увеличьте лимит ключа, затем повторите запрос. | | `forbidden` | `403` | `false` | Операция запрещена ключу или аккаунту: модель недоступна за бонус, запрос пришёл с IP вне разрешённого списка либо модель не входит в группу ключа. | Прочитайте сообщение. Для аккаунта с бонусом пополнение открывает доступ ко всем моделям. | | `not_found` | `404` | `false` | Неизвестная модель или модель без цены в текстовом API и Capabilities API, неизвестная возможность либо задача другого аккаунта. В API изображений и видео модель вне каталога даёт `400 bad_request`; сообщение указывает это. | Проверьте ID и аккаунт ключа; для возможностей используйте `suggestions`. | | `result_expired` | `404` | `false` | Только у `POST /v1/capabilities/run` с `operation: "result"`, если для `request_id` нет сохранённого результата. Срок хранения — один час. | Выполните возможность заново. | | `idempotency_conflict` | `409` | `false` | `Idempotency-Key` использован с другим телом или путём либо первый запрос с ним ещё выполняется. | Повторно используйте ключ только для полностью идентичного запроса. | | `rate_limit_exceeded` | `429` | `true` | Ключ превысил частоту запросов, включая лимиты бесплатных моделей. В текстовом API также может означать перегрузку модели («This model is receiving too many requests»). | Подождите `Retry-After` секунд, также указанных в `retry_after_seconds`, затем повторите. | | `internal_error` | `500` | `true` | Непредвиденная внутренняя ошибка. | Повторите один раз; если ошибка осталась, передайте поддержке `request_id`. | | `not_implemented` | `501` | `false` | Метод опубликован, но пока не поддерживается данным шлюзом. | Не повторяйте; используйте другой метод. | | `processing_unavailable` | `503` | `true` | Модель временно недоступна или перегружена на стороне сервиса. Также загрузка при недоступном хранилище («File storage is temporarily unavailable. Retry later; nothing was stored.»). | Повторите позже с увеличением задержки или выберите другую модель. | | `processing_timeout` | `503` | `true` | Обработка не завершилась вовремя. | Повторите с увеличением задержки. | | `processing_failed` | `503` | `true` | Другая ошибка обработки на стороне сервиса. | Повторите с увеличением задержки. | | `result_transfer_failed` | `503` | `true` | Результат сгенерирован, но не сохранён. Также загрузка, файл которой не удалось сохранить («The file could not be stored on our side. Retry; nothing was stored.»). | Повторите с увеличением задержки. | Слишком большое тело запроса в 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](/realtime-api). Подпись вебхука проверяет ваш обработчик, поэтому BeatAPI не возвращает отдельный код для её проверки. См. [вебхуки](/webhooks). | Код | HTTP | `retryable` | Когда возникает | | ------------------------------- | ----- | ----------- | --------------------------------------------------------------------------------------------------------------- | | `realtime_disabled` | `503` | `false` | Видео в реальном времени не включено на данном сервере. Самостоятельно включить нельзя; обратитесь в поддержку. | | `realtime_capacity_unavailable` | `503` | `true` | Временно нет ресурсов Realtime. Повторите позже с увеличением задержки; точное ожидание не указано. | | `realtime_session_expired` | `410` | `false` | Сессия больше не действует; создайте новую. | | `origin_not_allowed` | `403` | `false` | Источник браузерного запроса не разрешён для сессии. | | `invalid_client_secret` | `401` | `false` | Секрет сессии неверен или больше не действует. | | `transport_not_allowed` | `400` | `false` | Запрошенный транспорт не разрешён. | ## Текстовый API В `POST /v1/chat/completions`, `POST /v1/responses` и `POST /v1/messages` ошибки могут возникнуть на двух этапах, с разными форматами ответа. **1. До вызова модели.** Ошибки отсутствующего или неверного ключа, доступа за бонус, разрешённых IP, группы ключа, маршрутизации и частоты запросов используют [объект BeatAPI](#the-error-object): `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`): ```json { "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`): ```json { "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`. | HTTP | Код | Что делать | | ----- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `bad_request` или `content_policy_violation` | Исправьте запрос или вход; не повторяйте без изменений. Английское сообщение модели о параметрах, например длинном контексте, приходит в `message`. | | `402` | `insufficient_credits` | Пополните баланс или увеличьте лимит ключа. | | `404` | `not_found` | Неизвестная модель: получите список доступных через `GET /v1/models`. | | `413` | `read_request_body_failed` | Уменьшите тело. У этого кода нет `retryable`. | | `429` | `rate_limit_exceeded` | Превышен ваш лимит или модель перегружена. Повторите с увеличением задержки; на этом этапе `Retry-After` не гарантируется. | | `500` | `internal_error` сервиса или `temporary_error` модели | Повторите один-два раза с увеличением задержки. | | `503` | `model_unavailable`, `upstream_timeout` или `temporary_error` | Повторите с увеличением задержки или выберите другую модель. | ## Правила повторных попыток * **Не повторяйте без изменений** (`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`.