Обработка ошибок

Если запрос к API Aiberm завершается неудачей, API возвращает JSON-объект ошибки. Используйте HTTP-код статуса, error.code и error.message, чтобы понять причину и решить, что делать дальше.

Если нужна поддержка, приложите полный ответ об ошибке со всеми request id.

Формат ответа об ошибке

{
  "error": {
    "message": "用户额度不足, 剩余额度: ¥0.00 (request id: 20260622xxxxxxxx)",
    "type": "new_api_error",
    "code": "insufficient_user_quota"
  }
}

Поле	Значение
`message`	Человекочитаемое сообщение об ошибке. Хвост `(request id: ...)` — идентификатор трассировки этого запроса. Указывайте его при обращении в поддержку.
`code`	Идентификатор категории ошибки. Сопоставьте его с типичными ошибками ниже.
`type`	Маркер источника ошибки. В большинстве случаев его не нужно обрабатывать напрямую.

Если в message несколько значений (request id: ...), это нормально: запрос прошёл через несколько слоёв сервиса. При обращении в поддержку копируйте полное сообщение об ошибке.

HTTP-коды статуса

Статус	Значение	Что делать
`400`	Неверный формат запроса	Проверьте JSON запроса, обязательные поля, `Content-Type` и имя модели.
`401`	Недействительный API-ключ	Проверьте, корректен ли ключ, не истёк ли он, не отключён ли и не исчерпана ли квота.
`403`	Нет прав или недостаточно баланса	Проверьте баланс аккаунта, права токена, доступ к модели и исходный IP.
`404`	Ресурс не найден	Проверьте URL эндпоинта и написание имени модели.
`429`	Слишком много запросов	Снизьте параллелизм или частоту запросов и повторите позже.
`500`	Внутренняя ошибка сервера	Повторите позже. Если ошибка сохраняется, свяжитесь с поддержкой и укажите `request id`.
`503`	Сервис временно недоступен	У модели сейчас нет доступного маршрута. Повторите позже или обратитесь в поддержку.

Ошибки API-ключа и аутентификации

Эти ошибки обычно возвращают 401.

Возможное сообщение	Типичная причина	Как исправить
`无效的令牌`	API-ключ неверен или не существует.	Проверьте, что ключ полный и без лишних или пропущенных символов. Скопируйте его заново из консоли.
`该令牌已过期`	Срок действия токена истёк.	Сгенерируйте токен заново в консоли или продлите срок его действия.
`该令牌额度已用尽`	Квота, выделенная этому токену, исчерпана.	Увеличьте квоту токена или используйте другой токен с достаточным лимитом.
`该令牌状态不可用`	Токен отключён.	Включите токен в консоли или создайте новый.
`未提供令牌`	В запросе нет API-ключа.	Добавьте в заголовки `Authorization: Bearer sk-xxxxxx`.

Ошибки прав и баланса

Эти ошибки обычно возвращают 403.

Возможное сообщение	Типичная причина	Как исправить
`用户额度不足, 剩余额度: ...`	Баланса аккаунта недостаточно для этого запроса.	Пополните счёт и повторите запрос.
`预扣费额度失败, 用户剩余额度: ...`	Баланса недостаточно, чтобы покрыть оценочную стоимость запроса.	Пополните счёт или уменьшите `max_tokens` и сократите входные данные.
`您的 IP 不在令牌允许访问的列表中`	У токена есть белый список IP, и текущий IP в него не входит.	Используйте разрешённый IP или обновите список в консоли.
`用户已被封禁`	Аккаунт заблокирован.	Обратитесь в поддержку за подробностями.
`无权访问 xxx 分组`	У токена нет доступа к запрошенной группе.	Используйте разрешённую группу или запросите доступ.
`该令牌无权访问模型 xxx`	В списке разрешённых моделей токена нет этой модели.	Используйте разрешённую модель или обновите права токена в консоли.

Ошибки содержимого запроса

Эти ошибки обычно возвращают 400.

Возможное сообщение	Типичная причина	Как исправить
`Invalid request, ...`	Тело запроса не удаётся разобрать.	Проверьте валидность JSON и что `Content-Type` равен `application/json`.
`未指定模型名称，模型名称不能为空`	В запросе нет поля `model`.	Добавьте корректное поле `model` в тело запроса.
Сообщения вроде `检测到敏感词`	Входные данные сработали на правило безопасности контента.	Измените ввод и повторите запрос.

Ошибки лимита запросов

Эти ошибки обычно возвращают 429.

Возможное сообщение	Типичная причина	Как исправить
`您已达到请求数限制：N分钟内最多请求M次`	Достигнут лимит успешных запросов.	Снизьте частоту запросов и повторите после сброса окна лимита.
`您已达到总请求数限制：...，包括失败次数...`	Достигнут общий лимит запросов, включая неудачные.	Проверьте, нет ли цикла повторных неудачных запросов, устраните причину и повторите.

Ошибки модели и маршрута

Эти ошибки обычно возвращают 404 или 503.

Возможное сообщение	Типичная причина	Как исправить
`模型不存在`	Имя модели написано неверно или эта модель не включена для токена.	Проверьте имя модели и права токена на модели.
`无可用渠道`	У модели сейчас нет доступного маршрута.	Повторите позже. Если недоступность сохраняется, обратитесь в поддержку.

Ошибки сервера

Эти ошибки обычно возвращают 500 или 503.

Возможное сообщение	Типичная причина	Как исправить
Сообщения о внутренней ошибке	Временная проблема сервера или временная недоступность вышестоящего сервиса.	Повторите позже. Если ошибка сохраняется, свяжитесь с поддержкой и укажите `request id`.

Перед обращением в поддержку

Чтобы мы быстрее нашли причину, предоставьте:

Полный ответ об ошибке, включая message, code и каждый request id.
Примерное время возникновения проблемы.
Имя модели и URL эндпоинта, который вы вызывали.
Первые символы API-ключа, например sk-abcd.... Не присылайте полный ключ.