Hibák és korlátok

A hiba a meghívott API formátumában érkezik: az error objektum OpenAI esetén, a {"type": "error", "error": {...}} Anthropic esetén, az error objektum a status és details mezőkkel Gemini esetén. Ezért az SDK-k szokásos API-hibaként ismerik fel őket.

• error.code és error.reason — az alábbi táblázat szerinti hibaosztály; a két érték megegyezik. error.type — a formátum szabványos értéke (például invalid_request_error vagy server_error).
• error.request_id (Anthropic esetén a request_id legfelső szinten), a X-Request-ID fejléc és az üzenetszöveg vége — a kérés azonosítója.
• Gemini esetén az osztály ebben található: error.details: ErrorInfo.reason — ugyanaz a kód nagybetűkkel (például MODEL_OVERLOADED), domain — ailoot.ai; a kérés azonosítója pedig ebben: RequestInfo.requestId.
• Gemini formátumban az automatikusan nem ismételhető 5xx hiba és a result_pending_check 409-es státusszal és status ABORTEDértékkel érkezik: így a Gemini SDK és CLI nem ismétli meg őket automatikusan. A hibaosztály ebben található: ErrorInfo.reason (például MODEL_TIMEOUT vagy RESULT_PENDING_CHECK).
• Az OpenAI formátumú válaszban további legfelső szintű mezők is szerepelnek: code és message — a régebbi kliensek számára.

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

A modellválaszok és az eredményellenőrzés kódjai (502, 503 és 504) most a modellre vagy a kérésre hivatkoznak: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed és result_pending_check. Ha a kódja az error.code értékét korábbi értékekkel hasonlítja össze, cserélje azokat a táblázat kódjaira; a régi és új kódok megfeleltetésében segít a támogatás.

• Először ellenőrizze az X-Should-Retry értékét: ha false, result_pending_check vagy model_timeout érkezett, ne ismételje meg automatikusan. Keresse meg a Request ID-t a fiók előzményeiben: ott látható az eredmény és a terhelés.
• Az ismétlés akkor biztonságos, ha X-Should-Retry: true érkezett: várjon a Retry-After fejlécben megadott számú másodpercig. Az 5xx kód önmagában nem elég: az eredmény már megjelenhetett. Előbb ellenőrizze a fiók előzményeit, vagy írjon a támogatásnak a Request ID megadásával. Ez különösen fontos képek, videók, zene és hosszú ügynöklépések esetén.
• Az ismétlés nem segít: 400, 401, 402, 403, 404 — előbb javítsa a kérést, a kulcsot vagy az egyenleget.

A gyakoriság és az egyidejű kérések száma a teljes fiókjára korlátozott, nem egyes kulcsokra. Túllépéskor 429-es rate_limit_exceeded a következő fejléccel: Retry-After: 10. Ha maga a modell túlterhelt — 503-as model_overloaded a következővel: Retry-After: 30. Nagyobb terhelési igény esetén írjon a támogatásnak.

A költési korlátokat a kulcsnál kell megadni: a teljes keret — 402 api_key_quota_exhausted, az 5 órás, 1 napos és 7 napos időablakok — 429 usage_limit_reached. Részletek — Kulcsok és az API címe.

A modelllista nulla egyenlegnél is lekérhető; generáláshoz a zárolást fedező egyenleg szükséges. Az NVIDIA modellek (Nemotron és mások) közös várakozási soron keresztül működnek: nagy terhelésnél a válasz később érkezhet, vagy „a modell átmenetileg túlterhelt” hiba érkezik Retry-After fejléccel — a megadott idő után próbálja újra. Az árak a katalógusban találhatók, a terhelés a többi modellhez hasonlóan történik.

A méretkorlátokat a modell határozza meg: a kontextust (hány token küldhető el) és a válasz maximális hosszát. Ezek a katalógusban találhatók.