Leitfäden

Fehler, Limits und Wiederholungen

Lesen Sie Fehlerantworten und Rate-Limit-Header, wiederholen Sie Anfragen sicher und diagnostizieren Sie häufige Fehler.

Jede Felo API gibt einen JSON-Fehlertext mit einem stabilen Fehlercode und einer Request-ID zurück. Lesen Sie zuerst den HTTP-Status, dann den Code, dann die Meldung.

Fehlerformat

Aktuelle Produktionsantworten verwenden den HTTP-Status als status:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

Feld	Bedeutung
`status`	HTTP-Statuscode, im Textkörper wiederholt
`code`	Maschinenlesbarer Fehlercode
`message`	Für Menschen lesbare Erklärung
`request_id`	Undurchsichtige Kennung für diese Anfrage; geben Sie sie bei Support-Anfragen an

Einige ältere Endpoint-Beispiele verwenden status: "error" und einen anderen Codestring. Werten Sie den HTTP-Status und code aus, nicht den genauen Wortlaut von message.

Häufige Codes

HTTP	Code	Bedeutung	Was Sie tun sollten
400	Endpoint-spezifischer Validierungscode	Ein Parameter fehlt oder ist ungültig	Korrigieren Sie die Anfrage; wiederholen Sie sie nicht unverändert
401	`UNAUTHORIZED`	API-Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen	Senden Sie `Authorization: Bearer $FELO_API_KEY`; rotieren Sie den Schlüssel, wenn er widerrufen wurde
402	`INSUFFICIENT_CREDITS`	Nicht genügend Service-Guthaben	Laden Sie in Console Billing auf und versuchen Sie es dann erneut
404	Endpoint-spezifisch	Unbekanntes Modell, unbekannte Aufgabe oder unbekannte Route	Prüfen Sie Modell-ID oder Aufgaben-ID und den Endpoint-Pfad
429	`RATE_LIMITED`	Ein Rate-Limit wurde überschritten	Warten Sie `Retry-After` ab und versuchen Sie es dann erneut
5xx	`CHAT_FAILED`, `*_FAILED`, `SERVICE_UNAVAILABLE`	Upstream- oder Dienstfehler	Mit Backoff erneut versuchen; kontaktieren Sie den Support, wenn der Fehler bleibt

Endpoint-Referenzen listen die Codes, die für diesen Endpoint spezifisch sind. Beginnen Sie mit den Chat API-Fehlern oder mit der Referenz für den Endpoint, den Sie aufrufen.

Modellgenerierungs-Endpoints

POST /api/v1/images/generations und POST /api/v1/videos/generations geben Fehler auf Endpoint-Ebene im OpenAI-Format statt im oben beschriebenen Format zurück:

{
  "error": {
    "message": "Model kind does not match this generation endpoint",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_kind_mismatch"
  }
}

Die Request-ID steht im Antwort-Header X-Request-Id, nicht im Textkörper. Eine abgelehnte Anfrage erstellt keine Aufgabe. Sobald eine Aufgabe existiert, kommen die meisten Fehler als Endstatus der Aufgabe in einer 200-Antwort statt als HTTP-Fehler an: Prüfen Sie status auf failed oder interrupted und lesen Sie dann error.message. Siehe Bildgenerierung und Asynchrone Aufgaben.

Request-IDs

Felo-Fehlertexte enthalten request_id. Protokollieren Sie sie zusammen mit Endpoint, HTTP-Status, Fehlercode, Modell-ID und Aufgaben-ID. Protokollieren Sie niemals den vollständigen API-Schlüssel.

Die Model API akzeptiert außerdem einen optionalen Anfrage-Header X-Request-Id. Wenn Sie einen senden, wird er für Diagnosezwecke zurückgegeben, sodass Sie Ihre eigenen Logs einer Anfrage zuordnen können. Wenn Sie keinen senden, verwenden Sie die zurückgegebene request_id.

Rate-Limits

/v2/chat ist der einzige Felo-Endpoint mit dokumentierten erzwungenen Rate-Limits:

Pro API-Schlüssel, Zeitfenster von 1 Minute.
Pro Benutzer, Zeitfenster von 1 Minute.
Pro Benutzer, Zeitfenster von 1 Stunde.

Benutzer mit einem wirksamen bezahlten Felo-Abonnement, einschließlich Unternehmensabonnements, sind ausgenommen und erhalten keine X-RateLimit-*-Header. Wenn der Abonnementstatus nicht verifiziert werden kann, gelten die Limits weiterhin.

Header	Bedeutung
`X-RateLimit-Limit`	Limit der engsten derzeit wirksamen Dimension
`X-RateLimit-Remaining`	Minimal verbleibendes Kontingent über die drei Dimensionen
`X-RateLimit-Reset`	Unix-Zeitstempel in Sekunden, zu dem das aktuelle Zeitfenster zurückgesetzt wird
`Retry-After`	Bei einer 429-Antwort die empfohlene Verzögerung in Sekunden

Andere /v2/**-Endpoints haben derzeit keine erzwungenen Rate-Limits. Anfragen an die Model API können weiterhin durch den Upstream-Anbieter begrenzt werden, was als 429 auftreten kann.

Kodieren Sie numerische Limits nicht fest. Lesen Sie die Header jeder Antwort.

Wiederholungsrichtlinie

Situation	Erneut versuchen?
400, 401, 402, 404	Nein. Korrigieren Sie zuerst die Anfrage, den Schlüssel oder das Guthaben.
429	Ja, nach `Retry-After` oder `X-RateLimit-Reset`.
5xx, Timeouts, Verbindungsabbrüche	Ja, mit exponentiellem Backoff und Jitter.
Streaming-Verbindung mitten in der Antwort abgebrochen	Nur erneut versuchen, wenn Ihre Anwendung eine doppelte Generierung tolerieren kann.

Empfohlene Schleife:

Wiederholen Sie nur idempotente oder gefahrlos wiederholbare Anfragen.
Verwenden Sie exponentielles Backoff: beginnen Sie bei etwa 1 Sekunde, verdoppeln Sie den Wert und begrenzen Sie ihn auf 30 Sekunden.
Fügen Sie zufälligen Jitter hinzu, damit Clients nicht im Gleichschritt erneut versuchen.
Beenden Sie nach wenigen Versuchen und geben Sie den Fehler aus.
Beachten Sie bei 429 Retry-After statt Ihres eigenen Zeitplans.

Debugging-Reihenfolge

Prüfen Sie, ob der Schlüssel vorhanden und nicht widerrufen ist.
Rufen Sie GET /api/v1/models mit demselben Schlüssel auf, um die Authentifizierung zu bestätigen.
Senden Sie die kleinste gültige Anfrage an den Ziel-Endpoint.
Fügen Sie Streaming, Tools oder große Eingaben einzeln hinzu.
Prüfen Sie bei asynchroner Arbeit den Aufgabenstatus, bevor Sie erneut senden.