Fehler und Limits

Der Fehler entspricht dem Format der aufgerufenen API: Objekt error für OpenAI, {"type": "error", "error": {...}} für Anthropic und error mit den Feldern status und details für Gemini. Daher erkennen die SDKs sie als gewöhnliche API-Fehler.

• error.code und error.reason — die Fehlerklasse aus der folgenden Tabelle; beide Werte sind identisch. error.type — der Standardwert des Formats (zum Beispiel invalid_request_error oder server_error).
• error.request_id (bei Anthropic request_id auf oberster Ebene), der Header X-Request-ID und das Ende des Meldungstexts enthalten die Anfragekennung.
• Bei Gemini steht die Klasse in error.details: ErrorInfo.reason — derselbe Code in Großbuchstaben (zum Beispiel MODEL_OVERLOADED), domain — ailoot.ai; die Anfragekennung steht in RequestInfo.requestId.
• Im Gemini-Format werden ein nicht automatisch wiederholbarer 5xx-Fehler und result_pending_check mit Status 409 und status ABORTED geliefert, damit Gemini SDK und CLI sie nicht selbst wiederholen. Die Fehlerklasse steht in ErrorInfo.reason (zum Beispiel MODEL_TIMEOUT oder RESULT_PENDING_CHECK).
• Die Antwort im OpenAI-Format enthält außerdem die Felder auf oberster Ebene code und message für ältere Clients.

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

Die Codes für Modellantworten und Ergebnisprüfungen (502, 503 und 504) benennen jetzt das Modell oder die Anfrage: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed und result_pending_check. Wenn Ihr Code error.code mit früheren Werten vergleicht, ersetzen Sie diese durch die Codes aus der Tabelle. Die Zuordnung alter zu neuen Codes erläutert der Support.

• Prüfen Sie zuerst X-Should-Retry: Bei false, result_pending_check oder model_timeout nicht automatisch wiederholen. Suchen Sie die Request ID im Verlauf des Kundenbereichs; dort sehen Sie Ergebnis und Abbuchung.
• Eine Wiederholung ist sicher, wenn X-Should-Retry: true vorliegt: Warten Sie Retry-After Sekunden. Bei 5xx reicht der Code allein nicht aus; ein Ergebnis könnte bereits vorliegen. Prüfen Sie zuerst den Verlauf im Kundenbereich oder kontaktieren Sie den Support mit der Request ID. Dies ist besonders wichtig für Bilder, Video, Musik und lange Agentenschritte.
• Eine Wiederholung hilft nicht: 400, 401, 402, 403, 404; korrigieren Sie zuerst Anfrage, Schlüssel oder Guthaben.

Anfragerate und Anzahl gleichzeitiger Anfragen sind für Ihr gesamtes Konto begrenzt, nicht für einzelne Schlüssel. Bei Überschreitung erhalten Sie 429 rate_limit_exceeded mit dem Header Retry-After: 10. Ist das Modell selbst überlastet, erhalten Sie 503 model_overloaded mit Retry-After: 30. Wenn Sie ein höheres Anfragevolumen benötigen, schreiben Sie an den Support.

Ausgabenlimits werden am Schlüssel festgelegt: gesamtes Limit mit 402 api_key_quota_exhausted, Zeitfenster von 5 Stunden, 1 Tag und 7 Tagen mit 429 usage_limit_reached. Mehr dazu unter API-Schlüssel und API-Adresse.

Die Modellliste kann auch bei null Guthaben abgefragt werden; zur Generierung ist Guthaben für die Reservierung erforderlich. NVIDIA-Modelle wie Nemotron verwenden eine gemeinsame Warteschlange. Bei hoher Last kann die Antwort später eintreffen oder ein Fehler „Modell vorübergehend überlastet“ mit Retry-After auftreten. Wiederholen Sie nach der angegebenen Zeit. Preise stehen im Katalog; die Abbuchung erfolgt wie bei anderen Modellen.

Größenlimits legt das Modell fest: Kontext, also wie viele Tokens gesendet werden können, und maximale Antwortlänge. Sie stehen im Katalog.