Fehler und Limits

Der Fehler entspricht dem Format der aufgerufenen API: Objekt error bei OpenAI, {"type": "error", "error": {...}} bei Anthropic und error mit den Feldern status und details bei Gemini. Deshalb erkennen SDKs sie als normale API-Fehler.

• error.code und error.reason — Fehlerklasse aus der Tabelle unten; beide stimmen überein. error.type — Standardwert des Formats (zum Beispiel invalid_request_error oder server_error).
• error.request_id (bei Anthropic auf oberster Ebene als request_id ), der Header X-Request-ID und das Ende des Nachrichtentexts enthalten die Anfrage-ID.
• Bei Gemini steht die Klasse in error.details: ErrorInfo.reason — derselbe Code in Grossbuchstaben (zum Beispiel MODEL_OVERLOADED), domain — ailoot.ai; die Anfrage-ID steht in RequestInfo.requestId.
• Im Gemini-Format werden nicht automatisch wiederholbare 5xx-Fehler und result_pending_check mit Status 409 und status ABORTED zurückgegeben: So wiederholen Gemini SDK und CLI sie nicht automatisch. Die Fehlerklasse steht in ErrorInfo.reason (zum Beispiel MODEL_TIMEOUT oder RESULT_PENDING_CHECK).
• Antworten im OpenAI-Format enthalten zusätzlich 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"
      }
    ]
  }
}

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. Falls Ihr Code error.code mit früheren Werten vergleicht, ersetzen Sie diese durch die Codes aus der Tabelle; bei der Zuordnung alter zu neuer Codes hilft 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 bei X-Should-Retry: true: Warten Sie Retry-After Sekunden. Bei 5xx reicht der Code allein nicht: Das 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 bei Bildern, Videos, Musik und langen Agentenschritten.
• 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 kommt 429 rate_limit_exceeded mit dem Header Retry-After: 10. Ist das Modell selbst überlastet, kommt 503 model_overloaded mit Retry-After: 30. Benötigen Sie mehr Kapazität, kontaktieren Sie den Support.

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

Die Modellliste kann auch ohne Guthaben abgerufen werden; eine Generierung benötigt Guthaben für die Reservierung. NVIDIA-Modelle (Nemotron und weitere) verwenden eine gemeinsame Warteschlange: Bei hoher Last kann die Antwort später eintreffen oder der Fehler «Modell vorübergehend überlastet» mit dem Header Retry-After auftreten — versuchen Sie es nach der angegebenen Zeit erneut. Preise stehen im Katalog; die Abbuchung erfolgt wie bei den übrigen Modellen.

Grössenlimits legt das Modell fest: Kontextfenster (Anzahl möglicher Eingabetokens) und maximale Antwortlänge. Sie stehen im Katalog.