Virheet ja rajoitukset

Virhe saapuu kutsumasi APIn muodossa: objekti error OpenAIssa, {"type": "error", "error": {...}} Anthropicissa ja error kentillä status ja details Geminissä. Siksi SDK:t tunnistavat ne tavallisiksi API-virheiksi.

• error.code ja error.reason — alla olevan taulukon virheluokka; arvot ovat samat. error.type — muodon vakioarvo (esimerkiksi invalid_request_error tai server_error).
• error.request_id (Anthropicissa — request_id ylimmällä tasolla), otsake X-Request-ID ja viestitekstin loppu — pyynnön tunniste.
• Geminissä luokka on kentässä error.details: ErrorInfo.reason — sama koodi isoilla kirjaimilla (esimerkiksi MODEL_OVERLOADED), domain — ailoot.ai; pyynnön tunniste on kentässä RequestInfo.requestId.
• Gemini-muodossa 5xx-virhe, jota ei saa yrittää automaattisesti uudelleen, ja result_pending_check saapuvat tilakoodilla 409 ja status ABORTED: näin Gemini SDK ja CLI eivät toista niitä automaattisesti. Virheluokka on kentässä ErrorInfo.reason (esimerkiksi MODEL_TIMEOUT tai RESULT_PENDING_CHECK).
• OpenAI-muotoisessa vastauksessa on lisäksi ylimmän tason kentät code ja message — vanhoja asiakkaita varten.

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

Mallivastausten ja tuloksen tarkistuksen koodit (502, 503 ja 504) nimeävät nyt mallin tai pyynnön: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed ja result_pending_check. Jos koodisi vertaa error.code aiempiin arvoihin, korvaa ne taulukon koodeilla; aiempien ja uusien koodien vastaavuuden kertoo tuki.

• Tarkista ensin X-Should-Retry: arvolla false, result_pending_check tai model_timeout älä yritä automaattisesti uudelleen. Etsi Request ID hallintapaneelin historiasta: siellä näkyvät tulos ja veloitus.
• Uudelleenyritys on turvallinen, kun saat X-Should-Retry: true -otsakkeen: odota Retry-After sekuntia. 5xx-virheissä pelkkä koodi ei riitä: tulos on voinut jo saapua. Tarkista ensin historia hallintapaneelista tai ota yhteyttä tukeen Request ID:n kanssa. Tämä on erityisen tärkeää kuville, videoille, musiikille ja pitkille agenttiaskelille.
• Uudelleenyritys ei auta: 400, 401, 402, 403, 404 — korjaa ensin pyyntö, avain tai saldo.

Pyyntötiheyttä ja samanaikaisten pyyntöjen määrää rajoitetaan koko tilille, ei yksittäiselle avaimelle. Ylityksestä saat 429 rate_limit_exceeded otsakkeella Retry-After: 10. Jos itse malli on ylikuormittunut — 503 model_overloaded kentällä Retry-After: 30. Jos tarvitset suurempaa kuormitusta, ota yhteyttä tukeen.

Kulutusrajat asetetaan avaimelle: kokonaisraja — 402 api_key_quota_exhausted, jaksot 5 tuntia, 1 päivä ja 7 päivää — 429 usage_limit_reached. Lisätietoja — Avaimet ja API-osoite.

Malliluettelon voi pyytää myös nollasaldolla; generointi vaatii saldoa varaukseen. NVIDIA-mallit (Nemotron ja muut) käyttävät yhteistä jonoa: suurella kuormituksella vastaus voi saapua myöhemmin tai palautuu virhe ”malli on tilapäisesti ylikuormittunut” Retry-After-otsakkeella — yritä uudelleen ilmoitetun ajan kuluttua. Hinnat ovat luettelossa, ja veloitus toimii kuten muillakin malleilla.

Malli määrittää kokorajat: kontekstin (lähetettävien tokenien määrä) ja vastauksen enimmäispituuden. Ne ilmoitetaan luettelossa.