Zurück zum Blog

FehlerbehebungAnleitung

Häufige Verbindungsfehler und wie man sie behebt

Was 401, 402, 400, 404, 413, 429 und 503 bedeuten, wenn du dich mit der CheapTokens API verbindest, wie die Antworten aussehen und wie man jeden Fehler behebt.

Von CheapTokens TeamVeröffentlicht am 3 Min. Lesezeit

Liste der HTTP-Statuscodes 401, 402, 400, 404 und 429 mit kurzen Erklärungen in einem Terminal
Auf dieser Seite
  1. Kurze Prüfung
  2. 401 — Ungültiger API-Schlüssel
  3. 402 — leeres Guthaben oder kein Schlüssel in der Anfrage
  4. 404 — falsche Adresse
  5. 400 — Modell nicht gefunden
  6. 413 — Anfrage zu groß
  7. 429 — zu viele Anfragen
  8. 503 — Modell vorübergehend nicht verfügbar
  9. Lange Wartezeiten und Timeouts

Fast jedes Verbindungsproblem lässt sich auf vier Dinge zurückführen: die Adresse, den Schlüssel, die Modell-ID und das Guthaben. Beginne mit der kurzen Prüfung unten und suche dann deinen Statuscode. Die hier zitierten Antwort-Bodies sind die tatsächlichen Antworten der API (Oktober 2026).

Kurze Prüfung#

bash
# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

Wenn der erste Befehl fehlschlägt, kann die Ursache das Netzwerk auf deiner Seite sein, ein Tippfehler in der Adresse — oder der Dienst selbst, der vorübergehend nicht verfügbar ist. Wenn nur der zweite fehlschlägt, schlage seinen Statuscode unten nach. Wenn beide funktionieren, aber dein Tool nicht, vergleiche die Einstellungen des Tools mit diesen beiden Befehlen.

401 — Ungültiger API-Schlüssel#

json
{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Clients im Anthropic-Stil erhalten denselben Fehler in ihrem Format:

json
{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

Ursachen:

  • der Schlüssel wurde mit einem fehlenden Zeichen, einem Leerzeichen oder Anführungszeichen kopiert;
  • der Schlüssel wurde im Dashboard rotiert — der alte funktioniert nicht mehr;
  • ein Schlüssel eines anderen Dienstes (zum Beispiel OpenAI) ist statt des CheapTokens-Schlüssels gesetzt;
  • die Umgebungsvariable ist in diesem Terminal leer: echo ${#CHEAPTOKENS_API_KEY} gibt ihre Länge aus.

Das Dashboard zeigt einen Schlüssel nur einmal. Wenn er verloren ist, drücke Rotate, um einen neuen zu erhalten, und aktualisiere ihn überall, wo er verwendet wird.

402 — leeres Guthaben oder kein Schlüssel in der Anfrage#

Die API gibt 402 in zwei verschiedenen Situationen zurück:

  1. Das Guthaben ist aufgebraucht. Anfragen werden aus dem Guthaben bezahlt; wenn es aufgebraucht ist, wird der Schlüssel pausiert. Lade im Dashboard auf, und Anfragen gehen wieder durch.
  2. Die Anfrage hat überhaupt keinen Schlüssel. Wenn der Header Authorization (oder x-api-key für Clients im Anthropic-Stil) fehlt, antwortet die API mit 402 und dem Typ insufficient_funds. Prüfe, ob dein Tool den Schlüssel wirklich sendet: Der OpenAI-Stil ist Authorization: Bearer <key>.

404 — falsche Adresse#

json
{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

Der Pfad enthält einen Tippfehler — hier completion statt completions. Weitere häufige Ursachen:

  • Die Basis-URL hat kein /v1. Clients im OpenAI-Stil benötigen https://api.cheaptokens.dev/v1. Ohne /v1 verfehlt die Anfrage die API und du erhältst eine einfache HTML-404-Seite statt JSON.
  • /v1 zweimal. Manche Clients fügen /v1 selbst hinzu; dann muss die Basis-URL das Root sein, https://api.cheaptokens.dev. Clients im Anthropic-Stil verwenden immer die Root-Adresse.

400 — Modell nicht gefunden#

json
{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

Die Modell-ID muss die vollständige ID sein, einschließlich des Präfixes vor dem Schrägstrich: deepseek-ai/DeepSeek-V4-Flash-0731, nicht deepseek-v4-flash. Groß- oder Kleinschreibung spielt keine Rolle. Die Fehlermeldung listet die verfügbaren IDs auf, und die vollständige Liste findest du immer unter GET /v1/models.

Ein 400 kommt auch bei einem fehlerhaften Anfrage-Body zurück — zum Beispiel bei einem leeren messages-Array (messages field is required and must be a non-empty array) oder einer Nachricht ohne role.

413 — Anfrage zu groß#

Der Anfrage-Body ist auf 16 MB begrenzt. Agents können das erreichen, indem sie riesige Dateien oder Logs in den Kontext packen. Sende nur die Teile, die das Modell benötigt, und kürze lange Tool-Ausgaben.

429 — zu viele Anfragen#

Wenn du 429 erhältst, drossle. Die Antwort enthält einen Header Retry-After mit der Anzahl der Sekunden, die du warten musst. Die offiziellen OpenAI-SDKs wiederholen automatisch (max_retries); warte in deinem eigenen Code Retry-After vor dem nächsten Versuch.

503 — Modell vorübergehend nicht verfügbar#

Ein Modell kann vorübergehend nicht verfügbar sein; die API antwortet dann mit 503 und dem Typ model_unavailable, und die Modellkarte auf der Website zeigt „temporarily unavailable“. Versuche es später erneut oder wechsle das Feld model auf ein anderes Modell — Schlüssel und Adresse bleiben gleich.

Lange Wartezeiten und Timeouts#

Reasoning-Modelle wie zai-org/GLM-5.3-Flash denken nach, bevor sie antworten, daher kann das erste Token eine Weile dauern. Verwende Streaming oder erhöhe das Client-Timeout — zum Beispiel timeout=120 im OpenAI SDK.

Tags: