Klaidos ir limitai

Klaida pateikiama iškviesto API formatu: objektas error OpenAI atveju, {"type": "error", "error": {...}} Anthropic atveju ir error su laukais status ir details Gemini atveju. Todėl SDK jas atpažįsta kaip įprastas API klaidas.

• error.code ir error.reason — klaidos klasė iš toliau pateiktos lentelės; jie sutampa. error.type — standartinė formato reikšmė (pavyzdžiui, invalid_request_error arba server_error).
• error.request_id (Anthropic atveju — request_id aukščiausiame lygyje), antraštė X-Request-ID ir pranešimo teksto pabaiga — užklausos identifikatorius.
• Gemini atveju klasė yra lauke error.details: ErrorInfo.reason — tas pats kodas didžiosiomis raidėmis (pavyzdžiui, MODEL_OVERLOADED), domain — ailoot.ai; užklausos identifikatorius — lauke RequestInfo.requestId.
• Gemini formatu 5xx klaida, kurios negalima automatiškai kartoti, ir result_pending_check pateikiamos su būsena 409 ir status ABORTED: taip Gemini SDK ir CLI patys jų nekartoja. Klaidos klasė — lauke ErrorInfo.reason (pavyzdžiui, MODEL_TIMEOUT arba RESULT_PENDING_CHECK).
• OpenAI formato atsakyme taip pat yra aukščiausio lygio laukai code ir message — senesniems klientams.

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

Modelio atsakymų ir rezultato patikros kodai (502, 503 ir 504) dabar įvardija modelį arba užklausą: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed ir result_pending_check. Jei jūsų kodas lygina error.code su ankstesnėmis reikšmėmis, pakeiskite jas lentelės kodais; ankstesnių ir naujų kodų atitikmenis nurodys pagalbos tarnyba.

• Pirmiausia pažiūrėkite į X-Should-Retry: kai false, result_pending_check arba model_timeout nekartokite automatiškai. Raskite Request ID paskyros istorijoje: ten matomas rezultatas ir nurašymas.
• Kartoti saugu gavus X-Should-Retry: true: palaukite Retry-After sekundžių. 5xx atveju vien kodo nepakanka: rezultatas jau galėjo atsirasti. Pirmiausia patikrinkite paskyros istoriją arba rašykite pagalbos tarnybai, nurodydami Request ID. Tai ypač svarbu vaizdams, vaizdo įrašams, muzikai ir ilgiems agentų žingsniams.
• Pakartojimas nepadės: 400, 401, 402, 403, 404 — pirmiausia pataisykite užklausą, raktą arba balansą.

Dažnis ir vienalaikių užklausų skaičius ribojami visai jūsų paskyrai, o ne atskiram raktui. Viršijus grąžinama 429 rate_limit_exceeded su antrašte Retry-After: 10. Jei perkrautas pats modelis — 503 model_overloaded su Retry-After: 30. Jei reikia didesnės apkrovos, kreipkitės į pagalbos tarnybą.

Išlaidų limitai nustatomi raktui: bendras limitas — 402 api_key_quota_exhausted, 5 valandų, 1 dienos ir 7 dienų langai — 429 usage_limit_reached. Plačiau — Raktai ir API adresas.

Modelių sąrašo galima prašyti ir esant nuliniam balansui; generavimui reikia lėšų rezervui. NVIDIA modeliai (Nemotron ir kiti) veikia per bendrą eilę: esant didelei apkrovai atsakymas gali vėluoti arba bus grąžinta klaida „modelis laikinai perkrautas“ su Retry-After antrašte — kartokite praėjus nurodytam laikui. Kainos pateiktos kataloge, nurašymas vyksta kaip kitų modelių.

Dydžio limitus nustato modelis: kontekstą (kiek žetonų galima siųsti) ir didžiausią atsakymo ilgį. Jie nurodyti kataloge.