Ошибки и лимиты

Ошибка приходит в формате того API, который вы вызвали: объект error для OpenAI, {"type": "error", "error": {...}} для Anthropic и error с полями status и details для Gemini. Поэтому SDK распознают их как обычные ошибки API.

• error.code и error.reason — класс ошибки из таблицы ниже, они совпадают. error.type — стандартное значение формата (например, invalid_request_error или server_error).
• error.request_id (в Anthropic — request_id на верхнем уровне), заголовок X-Request-ID и конец текста сообщения — идентификатор запроса.
• В Gemini класс лежит в error.details: ErrorInfo.reason — тот же код верхним регистром (например, MODEL_OVERLOADED), domain — ailoot.ai; идентификатор запроса — в RequestInfo.requestId.
• В формате Gemini ошибка 5xx, которую нельзя повторять автоматически, и result_pending_check приходят со статусом 409 и status ABORTED: так Gemini SDK и CLI не повторяют их сами. Класс ошибки — в ErrorInfo.reason (например, MODEL_TIMEOUT или RESULT_PENDING_CHECK).
• В ответе OpenAI-формата есть ещё поля верхнего уровня code и message — для старых клиентов.

{
  "code": "API_KEY_REQUIRED",
  "error": {
    "code": "invalid_api_key",
    "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
    "param": null,
    "reason": "invalid_api_key",
    "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
    "type": "invalid_request_error"
  },
  "message": "No API key was sent with the request. Nothing was charged. …"
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "reason": "invalid_api_key",
    "message": "… Nothing was charged. … Request ID: 94ed3e31-4373-41ce-bf8a-0d1ed3f7235e."
  },
  "request_id": "94ed3e31-4373-41ce-bf8a-0d1ed3f7235e"
}

{
  "error": {
    "code": 401,
    "status": "UNAUTHENTICATED",
    "message": "The API key is not valid. Nothing was charged. … Request ID: e7aa743b-9d0d-4064-b206-2562609f545b.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_API_KEY",
        "domain": "ailoot.ai",
        "metadata": {
          "code": "invalid_api_key",
          "reason": "invalid_api_key",
          "request_id": "e7aa743b-9d0d-4064-b206-2562609f545b"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "e7aa743b-9d0d-4064-b206-2562609f545b"
      }
    ]
  }
}

Коды для ответов модели и проверки результата (502, 503 и 504) теперь называют модель или запрос: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed и result_pending_check. Если ваш код сравнивает error.code с прежними значениями, замените их на коды из таблицы; соответствие прежних кодов новым подскажет поддержка.

• Сначала посмотрите на X-Should-Retry: при false, result_pending_check или model_timeout не повторяйте автоматически. Найдите Request ID в истории кабинета: там видно результат и списание.
• Повтор безопасен, когда пришёл X-Should-Retry: true: подождите Retry-After секунд. Для 5xx одного кода мало: результат мог уже появиться. Сначала проверьте историю в кабинете или напишите в поддержку с Request ID. Это особенно важно для картинок, видео, музыки и длинных агентных шагов.
• Не поможет повтор: 400, 401, 402, 403, 404 — сначала исправьте запрос, ключ или баланс.

Частота и число одновременных запросов ограничены для вашего аккаунта в целом, а не для отдельного ключа. При превышении придёт 429 rate_limit_exceeded с заголовком Retry-After: 10. Если перегружена сама модель — 503 model_overloaded с Retry-After: 30. Если нужна большая нагрузка, напишите в поддержку.

Лимиты трат задаются у ключа: общий лимит — 402 api_key_quota_exhausted, окна 5 часов, 1 день и 7 дней — 429 usage_limit_reached. Подробнее — Ключи и адрес API.

Список моделей можно запрашивать и при нулевом балансе; для генерации нужен баланс на резерв. Модели NVIDIA (Nemotron и другие) работают через общую очередь: при высокой нагрузке ответ может прийти позже или вернётся ошибка «модель временно перегружена» с заголовком Retry-After — повторите после указанного времени. Цены — в каталоге, списание как у остальных моделей.

Лимиты размера задаёт модель: контекст (сколько токенов можно отправить) и максимальная длина ответа. Они указаны в каталоге.