Fehler und Limits

Ein Fehler folgt 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 nachfolgenden Tabelle; beide stimmen überein. error.type — 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 Request-ID.
• Bei Gemini steht die Klasse in error.details: ErrorInfo.reason — derselbe Code in Großbuchstaben (zum Beispiel MODEL_OVERLOADED), domain — ailoot.ai; die Request-ID steht in RequestInfo.requestId.
• Im Gemini-Format werden ein 5xx-Fehler, der nicht automatisch wiederholt werden darf, und result_pending_check mit Status 409 sowie status ABORTED zurückgegeben: So wiederholen Gemini SDK und CLI sie nicht selbstständig. Die Fehlerklasse steht in ErrorInfo.reason (zum Beispiel MODEL_TIMEOUT oder RESULT_PENDING_CHECK).
• Eine 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üfung (502, 503 und 504) beziehen sich nun auf das Modell oder den Request: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed und result_pending_check. Vergleicht Ihr Code error.code mit früheren Werten, ersetzen Sie diese durch die Codes der Tabelle; bei der Zuordnung alter zu neuen Codes hilft der Support.

• Prüfen Sie zuerst X-Should-Retry: Bei false, result_pending_check oder model_timeout wiederholen Sie nicht automatisch. Suchen Sie die Request ID im Verlauf des Kundenbereichs: Dort sehen Sie Ergebnis und Abbuchung.
• Eine Wiederholung ist bei X-Should-Retry: true sicher: Warten Sie Retry-After Sekunden. Bei 5xx reicht der Code allein nicht aus: Das Ergebnis könnte bereits vorliegen. Prüfen Sie zuerst den Verlauf im Kundenbereich oder kontaktieren Sie den Support mit der Request ID. Das ist besonders wichtig bei Bildern, Video, Musik und langen Agentenschritten.
• Eine Wiederholung hilft nicht: 400, 401, 402, 403, 404 — korrigieren Sie zuerst Request, Schlüssel oder Guthaben.

Request-Häufigkeit und gleichzeitige Requests sind für Ihr gesamtes Konto begrenzt, nicht je Schlüssel. Bei Überschreitung erhalten Sie 429 rate_limit_exceeded mit dem Header Retry-After: 10. Ist das Modell selbst überlastet — 503 model_overloaded mit Retry-After: 30. Benötigen Sie eine höhere Last, kontaktieren Sie den Support.

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

Die Modellliste lässt sich auch ohne Guthaben abrufen; für eine Generierung muss die Reservierung gedeckt sein. NVIDIA-Modelle (Nemotron und andere) verwenden eine gemeinsame Warteschlange: Bei hoher Last kann die Antwort später eintreffen oder ein Fehler „Modell vorübergehend überlastet“ mit dem Header Retry-After erscheinen — versuchen Sie es nach der angegebenen Zeit erneut. Die Preise stehen im Katalog; abgerechnet wird wie bei den übrigen Modellen.

Größenlimits legt das Modell fest: Kontextfenster (wie viele Tokens Sie senden können) und maximale Antwortlänge. Sie stehen im Katalog.