Häufige Fragen

Fehlerbehebung

Beheben Sie Probleme mit Authentifizierung, Modellen, Streaming, Aufgaben und Rate Limits anhand einer symptomorientierten Checkliste.

Beginnen Sie beim Symptom und folgen Sie dann der Lösung. Die meisten Fehler gehen auf die Base-URL, den Schlüssel, die Modell-ID oder das Guthaben zurück.

Symptomtabelle

Symptom	Wahrscheinliche Ursache	Lösung
401 `UNAUTHORIZED`	Schlüssel fehlt, ist falsch, widerrufen oder wurde nicht gesendet	Senden Sie `Authorization: Bearer $FELO_API_KEY`; erstellen Sie einen neuen Schlüssel, wenn er widerrufen wurde
402 `INSUFFICIENT_CREDITS`	Das Guthaben deckt den Aufruf nicht ab	Laden Sie in Console Billing auf
404 bei jeder Anfrage	Die Base-URL enthält einen Pfad, den der Endpoint bereits anhängt	Verwenden Sie `https://openapi.felo.ai/api/v1` für OpenAI-Clients und `https://openapi.felo.ai/api` für Anthropic-Clients
404 bei einem Modell	Die Modell-ID ist nicht öffentlich, oder der Endpoint bedient sie nicht	Prüfen Sie die Modell-ID auf der Modellseite und in der Dokumentation des Endpoints
400 `model`- oder `max_tokens`-Fehler	Ein Pflichtfeld fehlt, oder das Modell akzeptiert die Form der Anfrage nicht	Fügen Sie `max_tokens` für Messages hinzu; entfernen Sie nicht unterstützte Felder
429	Rate-Limit oder ein Limit des Upstream-Anbieters	Lesen Sie `Retry-After`; siehe Fehler, Limits und Wiederholungen
5xx	Upstream- oder Dienstfehler	Mit Backoff erneut versuchen; geben Sie `request_id` an, wenn der Fehler bleibt
Stream verbindet, sendet aber nichts	Ein Proxy puffert die Antwort, oder der Ereignisparser erwartet das falsche Format	Lesen Sie den Stream schrittweise; deaktivieren Sie die Antwortpufferung in Ihrem Proxy
Aufgabe wird nie fertig	Falscher Abfrage-Endpoint, oder ein Endstatus wurde nicht behandelt	Fragen Sie den eigenen Status-Endpoint der Aufgabe ab und beenden Sie bei Endwerten
Tool-Aufrufe werden ignoriert	Das Modell gibt diese Funktion nicht an	Prüfen Sie `supported_parameters` im Katalog
Data API gibt 404 zurück	Das Präfix `/v1/beta` wurde doppelt hinzugefügt	Verwenden Sie den Pfad genau so, wie er in der Referenz steht

Authentifizierung

Ein widerrufener Schlüssel gibt eine Meldung zurück, die das Schlüsselpräfix nennt:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key has been revoked (keyPrefix=...)"
}

Checkliste:

Der Header lautet Authorization: Bearer <key> für die Model API und die Felo APIs.
Die Data API akzeptiert außerdem X-API-Key: <key>.
Der Schlüssel ist nicht in Anführungszeichen eingeschlossen, und es gibt kein abschließendes Zeilenzeichen aus einer kopierten Umgebungsvariable.
In der bereitgestellten Umgebung ist die Variable tatsächlich gesetzt; ein lokal funktionierender Schlüssel kann in der Produktion fehlen.
Der Schlüssel wurde nicht gelöscht oder rotiert. Ein gelöschter oder rotierter Schlüssel kann nicht erneut angezeigt werden; erstellen Sie einen neuen.

Siehe Authentifizierung für die Erstellung und die Limits von Schlüsseln.

Fallstricke bei der Base-URL

Client	Korrekte Base-URL
OpenAI SDK	`https://openapi.felo.ai/api/v1`
Anthropic SDK	`https://openapi.felo.ai/api`
Roher Modell-Endpoint	`https://openapi.felo.ai/api/v1/chat/completions`, `/responses` oder `/messages`
Data API	`https://openapi.felo.ai/v1/beta`
Felo `/v2`-APIs	`https://openapi.felo.ai/v2`

Zwei häufige Fehler:

/chat/completions an eine Base-URL anhängen, die das SDK bereits erweitert.
Die Anthropic-Base-URL auf https://openapi.felo.ai/api/v1 setzen. Das SDK hängt /v1/messages an, sodass die Anfrage zu /api/v1/v1/messages wird.

Probleme mit der Modell-ID

Modell-IDs sind die öffentlichen IDs aus dem Katalog, nicht die internen Namen des Upstream-Anbieters und kein Anzeigename.

Suchen Sie die ID auf der Modellseite oder in GET /api/v1/models.
Bestätigen Sie, dass das Modell das Protokoll unterstützt, das Sie aufrufen (supported_protocols).
Wenn Sie einen Kanal gebunden haben, bestätigen Sie, dass dieser Kanal für das Modell veröffentlicht und ausführbar ist. Ein nicht verfügbarer Kanal ist kein Fallback.

Siehe Kanäle und Anbieter-Routing.

Streaming-Probleme

Setzen Sie stream: true im Anfrage-Textkörper, nicht als Query-Parameter.
Lesen Sie den Antwort-Textkörper als Stream. Das Warten auf die vollständige Antwort macht Streaming zunichte.
Einige Proxys und Serverless-Plattformen puffern Antworten. Deaktivieren Sie die Pufferung für die Route, die die Anfrage proxyt.
Chat Completions streamt choices[0].delta, nicht choices[0].message. Der endgültige Inhalt kommt über viele Chunks hinweg an.
Ein Stream kann ohne sauberes Abschlussereignis enden, wenn die Verbindung abbricht. Behandeln Sie eine abgebrochene Verbindung als unvollständige Antwort.

Probleme mit asynchronen Aufgaben

Fragen Sie den Status-Endpoint ab, der zur Aufgabenfamilie gehört. Felo-Workflows verwenden GET /v2/tasks/{task_id}/status; Video- und Bildaufgaben von Modellen verwenden ihre eigenen Generierungs-Endpoints.
Beenden Sie bei jedem Endstatus, auch bei Fehlern und Abläufen, nicht nur bei Erfolg.
Video- und Bild-Callbacks werden derzeit ignoriert. Warten Sie nicht auf einen Webhook.
Eine Ergebnis-URL kann kurzlebig sein. Fordern Sie eine frische URL vom Status-Endpoint an, wenn ein Download abläuft.
Prüfen Sie die Aufgabe, bevor Sie erneut senden. Erneutes Senden einer laufenden Aufgabe erzeugt ein Duplikat, und beide werden abgerechnet.

Siehe Asynchrone Aufgaben.

Probleme mit der Data API

Behalten Sie den exakten Methodenpfad aus der Data API-Referenz bei.
Anfrage-Textkörper sind anbieterspezifisch. Ein Feld, das bei einem Anbieter funktioniert, funktioniert nicht unbedingt bei einem anderen.
Ein Anbieterfehler kann innerhalb einer 4xx-Antwort mit einer anbieterspezifischen Meldung ankommen. Protokollieren Sie request_id und den Antwort-Textkörper.

Sicherheitshinweise

Legen Sie einen API-Schlüssel niemals in Browsercode, einem Mobile-App-Bundle oder einem öffentlichen Repository ab. Halten Sie ihn auf einem Server und proxen Sie Anfragen.
Protokollieren Sie nicht den vollständigen Schlüssel. Protokollieren Sie ein Präfix, wenn Sie ihn identifizieren müssen.
Rotieren Sie einen Schlüssel sofort, wenn er möglicherweise preisgegeben wurde.

Bevor Sie den Support kontaktieren

Halten Sie Folgendes bereit:

Endpoint und HTTP-Methode.
HTTP-Status, code und request_id.
Modell-ID oder Aufgaben-ID.
Zeitstempel mit Zeitzone.
Einen minimalen Anfrage-Textkörper ohne Geheimnisse.

Senden Sie dies zusammen mit der E-Mail-Adresse des Kontos an den Support. Geben Sie nicht den vollständigen API-Schlüssel an.