Ошибки API: форматы и коды ответов

Формат ошибки (JSON)

При возникновении ошибки API возвращает HTTP-код 4xx или 5xx и тело ответа следующего вида:

{
  "status": false,
  "error": {
    "code": "invalid_request",
    "message": "Model is required",
    "type": "client"
  }
}

status

boolean

Логический флаг успеха (false при ошибке)

error.code

string

Уникальный код ошибки

error.message

string

Человекочитаемое описание проблемы

error.type

string

client, server, auth, rate_limit и др.

Основные HTTP-коды и ошибки

400

invalid_request

Неверный запрос: отсутствуют обязательные поля, некорректные значения

401

unauthorized

Неверный или отсутствующий токен API

403

forbidden

Нет прав доступа к ресурсу

404

not_found

Ресурс не найден (модель, ассистент, endpoint)

405

method_not_allowed

Неподдерживаемый HTTP-метод

413

payload_too_large

Слишком большой файл или JSON

429

rate_limit_exceeded

Превышен лимит запросов вендора (RPS или токены)

500

internal_error

Внутренняя ошибка сервиса

503

vendor_unavailable

Вендор временно недоступен или перегружен

Примеры

Ошибка 400 — отсутствует модель

{
  "status": false,
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: model",
    "type": "client"
  }
}