Błędy i limity

Błąd jest zwracany w formacie wywołanego API: obiekt error dla OpenAI, {"type": "error", "error": {...}} dla Anthropic i error z polami status i details dla Gemini. Dlatego SDK rozpoznają je jako zwykłe błędy API.

• error.code i error.reason — klasa błędu z poniższej tabeli; ich wartości są takie same. error.type — standardowa wartość dla danego formatu (na przykład invalid_request_error lub server_error).
• error.request_id (w Anthropic — request_id na najwyższym poziomie), nagłówek X-Request-ID i końcówka treści komunikatu — identyfikator żądania.
• W Gemini klasa znajduje się w error.details: ErrorInfo.reason — ten sam kod zapisany wielkimi literami (na przykład MODEL_OVERLOADED), domain — ailoot.ai; identyfikator żądania — w RequestInfo.requestId.
• W formacie Gemini błąd 5xx, którego nie wolno automatycznie ponawiać, oraz result_pending_check są zwracane ze statusem 409 i status ABORTED: dzięki temu Gemini SDK i CLI nie ponawiają ich samodzielnie. Klasa błędu znajduje się w ErrorInfo.reason (na przykład MODEL_TIMEOUT lub RESULT_PENDING_CHECK).
• Odpowiedź w formacie OpenAI zawiera również pola najwyższego poziomu code i message — dla starszych aplikacji klienckich.

{
  "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"
      }
    ]
  }
}

Kody dotyczące odpowiedzi modelu i sprawdzania wyniku (502, 503 i 504) wskazują teraz model lub żądanie: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed i result_pending_check. Jeśli Twój kod porównuje error.code z poprzednimi wartościami, zastąp je kodami z tabeli; informacje o powiązaniu dawnych kodów z nowymi poda pomoc techniczna.

• Najpierw sprawdź X-Should-Retry: przy false, result_pending_check lub model_timeout nie ponawiaj żądania automatycznie. Znajdź Request ID w historii panelu: widać tam wynik i pobraną opłatę.
• Ponowienie jest bezpieczne, gdy otrzymasz X-Should-Retry: true: poczekaj Retry-After sekund. W przypadku 5xx sam kod nie wystarcza: wynik mógł już się pojawić. Najpierw sprawdź historię w panelu lub skontaktuj się z pomocą techniczną, podając Request ID. To szczególnie ważne w przypadku obrazów, wideo, muzyki i długich kroków agentów.
• Ponowienie nie pomoże: 400, 401, 402, 403, 404 — najpierw popraw żądanie, klucz lub saldo.

Częstotliwość i liczba jednoczesnych żądań są ograniczone dla całego konta, a nie pojedynczego klucza. Po przekroczeniu limitu otrzymasz 429 rate_limit_exceeded z nagłówkiem Retry-After: 10. Jeśli przeciążony jest sam model — 503 model_overloaded z Retry-After: 30. Jeśli potrzebujesz większej przepustowości, skontaktuj się z pomocą techniczną.

Limity wydatków ustawia się dla klucza: całkowity limit — 402 api_key_quota_exhausted, okna 5 godzin, 1 dzień i 7 dni — 429 usage_limit_reached. Więcej informacji — Klucze i adres API.

Listę modeli można pobrać także przy zerowym saldzie; generowanie wymaga salda wystarczającego na rezerwę. Modele NVIDIA (Nemotron i inne) korzystają ze wspólnej kolejki: przy dużym obciążeniu odpowiedź może nadejść później albo zostanie zwrócony błąd „model jest chwilowo przeciążony” z nagłówkiem Retry-After — ponów żądanie po wskazanym czasie. Ceny są w katalogu, a opłaty pobiera się tak jak dla pozostałych modeli.

Limity rozmiaru zależą od modelu: kontekst (ile tokenów można wysłać) i maksymalna długość odpowiedzi. Są podane w katalogu.