API-Fehler: Ursachen und Lösungen
Jeder Artikel beginnt mit der Antwort und zeigt einen Befehl, mit dem Sie die Ursache selbst bestätigen können. Die Fehlermeldungen stehen im englischen Original – so, wie sie in Ihrem Terminal erscheinen.
Unexpected token '<' beim Aufruf einer OpenAI-kompatiblen APIIhr Client hat HTML statt JSON bekommen. Fast immer fehlt der Base URL das /v1 oder es steht doppelt darin. So bestätigen Sie es mit einem Befehl und beheben es.401 invalid API key – wenn der Schlüssel richtig aussieht und trotzdem scheitertEin 401 mit einem gerade kopierten Schlüssel liegt meist an Leerzeichen, am falschen Header oder an einem Schlüssel, der das Modell nicht erreichen darf. So finden Sie heraus, was es ist.404 auf /v1/chat/completions, obwohl der Endpunkt eindeutig existiertEin 404 von einem Endpunkt, der nachweislich läuft, ist fast immer ein GET, wo die API ein POST erwartet, oder ein Pfad, der um ein Segment daneben liegt. So unterscheiden Sie beides.524-Timeout bei langen API-AnfragenEin 524 kommt von einem CDN vor der API, nicht vom Modell. Er löst aus, wenn der Ursprungsserver zu lange nichts sendet – deshalb überleben Streaming-Anfragen und Anfragen ohne Streaming nicht.Model not found – wenn der Modellname fast stimmtDieser Fehler heißt fast immer, dass der Modellname nicht exakt passt oder Ihr Schlüssel das Modell nicht erreichen darf. So listen Sie auf, was Sie wirklich aufrufen können.429 von einem API-Gateway bedeutet zwei verschiedene DingeEin Gateway antwortet mit 429, wenn Ihr Guthaben aufgebraucht ist, und auch, wenn der Upstream ausgelastet ist. Das eine lohnt einen erneuten Versuch, das andere nie. So erkennen Sie es am Response-Body.CORS-Fehler beim Aufruf einer KI-API aus dem BrowserDer CORS-Fehler ist das Symptom. Das eigentliche Problem: Eine Anfrage aus dem Browser gibt Ihren API-Schlüssel an jeden Besucher weiter. Was Sie stattdessen tun sollten und warum keine Header-Einstellung das behebt.400, wenn man bei einem Reasoning-Modell einen Tool-Aufruf erzwingttool_choice auf any oder tool wird von Modellen abgelehnt, die vor jeder Antwort nachdenken. Was Sie stattdessen senden und welche weiteren Parameter diese Modelle verweigern.Anfragen brechen hinter Cloudflare nach genau 100 Sekunden abEine lange Completion scheitert nach fast genau 100 Sekunden mit 524 oder abgebrochenem Stream. Die Zahl ist ein Proxy-Limit von Cloudflare, nicht das Ihres Servers. So bestätigen Sie es, und drei Wege drumherum.Das Modell liefert einen leeren String, und trotzdem wird abgerechnetDie Antwort kommt mit HTTP 200, content ist ein leerer String, und im Nutzungslog wurden Output-Tokens berechnet. Bei Reasoning-Modellen ist fast immer max_tokens aufgebraucht, bevor sichtbarer Text entsteht.Eine Streaming-Antwort bricht mitten im Satz abTokens kommen an, dann hören sie auf, und es gibt keinen Fehler. Der Unterschied zwischen einem fertigen und einem gekappten Stream ist eine einzige Zeile im SSE-Body – und die meisten Clients prüfen sie nie.Ein Modell, das gestern lief, scheitert jetzt für alle in derselben SchlüsselgruppeEin bisher funktionierendes Modell liefert für jeden Schlüssel einer Gruppe Fehler, andere Gruppen sind nicht betroffen. Das ist Routing, nicht das Modell: Ein kaputtes Upstream-Konto kann eine ganze Gruppe lahmlegen.Die Rechnung ist höher, als die Token-Zahl rechtfertigtDie geloggten Token-Summen wirken bescheiden, die Abbuchung nicht. Bei Modellen der Claude-Familie liegt es meist an der Cache-Richtung: Ein Cache-Schreibvorgang kostet mehr als normaler Input, ein Cache-Lesevorgang nur einen Bruchteil, und dieselben Tokens können sich um das Zwölffache unterscheiden.Claude Code und Codex brauchen beim selben Gateway unterschiedliche Base URLsDasselbe Gateway, derselbe Schlüssel, zwei Coding-Agenten – und eine Base URL, die im einen funktioniert, scheitert im anderen. Die Regel ist einfach, sobald Sie wissen, welcher Client den Pfad selbst anhängt.405 Method Not Allowed beim Aufruf einer KI-APIEin 405 an einem KI-Endpunkt bedeutet fast nie, dass die Methode falsch ist. Es bedeutet, dass das POST irgendwo gelandet ist, das nur Seiten ausliefert – meist auf der nackten Domain, weil der Base URL /v1 fehlt. So bestätigen Sie es mit einem Befehl.404 auf /responses – auch die Responses API braucht das VersionspräfixClients, die von chat/completions auf die Responses API umsteigen, lassen oft das Versionspräfix weg. Das 404 kommt vom Edge, bevor irgendein API-Code läuft, deshalb erscheint der Aufruf nie in Ihrem Nutzungslog.context_length_exceeded – was wirklich zum Limit zähltDas Limit umfasst die ganze Unterhaltung plus den für die Antwort reservierten Platz, nicht nur Ihre letzte Nachricht. Warum das Kürzen des Prompts oft nicht hilft und was Sie stattdessen kürzen sollten.529 overloaded_error von Claude – was das ist und was zu tun ist529 heißt: Der Upstream ist gerade ausgelastet. Das ist kein Kontingentproblem und nichts, was Ihr Schlüssel lösen kann. Wie Sie es von 429 unterscheiden und welches Retry-Muster wirklich hilft.401 mit einem Schlüssel, der garantiert stimmt – prüfen Sie das Header-FormatEin Schlüssel kann völlig gültig sein und trotzdem ein 401 auslösen, wenn der Header falsch gebaut ist. Die drei Wege, wie das schiefgeht, und wie Sie sehen, welchen Header Ihr Client wirklich gesendet hat.400 unsupported parameter bei einem Reasoning-ModellReasoning-Modelle lehnen Sampling-Parameter ab, die jedes andere Modell akzeptiert. Welche Sie entfernen müssen, warum der Standard meist ohnehin das ist, was Sie wollten, und wie Sie einen Codepfad für beide Modellarten behalten.Token-Verbrauch fehlt in einer gestreamten AntwortEine gestreamte Antwort enthält keine Token-Zahlen, solange Sie sie nicht anfordern. Wie Sie sie einschalten, wo der letzte Chunk ankommt und was zu tun ist, wenn ein Gateway ihn nicht sendet.400 bei einem Tool-Aufruf – jedes tool_use braucht ein passendes tool_resultDer Fehler zeigt sich einen Durchlauf später als der eigentliche Fehler – das macht ihn so verwirrend. Die Paarungsregel, die Reihenfolgeregel und wie Sie ihn gezielt reproduzieren, um ihn ein für alle Mal zu beheben.Der JSON-Modus liefert trotzdem Text, der sich nicht parsen lässtresponse_format schränkt die Form ein, nicht den Abschluss. Abschneiden, fehlende Schema-Durchsetzung und Fließtext um das Objekt herum lassen das Parsen jeweils auf andere Weise scheitern.Der Aufruf funktioniert mit curl, aber nicht aus Ihrer AnwendungGleicher Schlüssel, gleiche URL, anderes Ergebnis. Der Unterschied liegt fast immer in etwas, das curl nicht tut: ein Proxy, eine veraltete Umgebungsvariable, eine IP-Beschränkung oder eine Bibliothek, die Ihre Anfrage umschreibt.SSL certificate verify failed beim Aufruf einer KI-APIEin TLS-Fehler im SDK, während curl funktioniert, ist fast immer ein Firmen-Proxy oder Virenscanner, der den Verkehr neu signiert. Warum das Abschalten der Prüfung die falsche Lösung ist und welche drei richtig sind.socket hang up mitten in einer gestreamten AntwortEin Stream, der unterwegs abbricht, hinterlässt eine Teilantwort und keinen Fehler vom Modell. Wie Sie einen Netzwerkabbruch von einem Abbruch beim Upstream unterscheiden und was jeweils zu tun ist.Claude Code: API Error 400 prompt is too longDer Fehler nennt die Anfrage, aber die Ursache ist der angesammelte Sitzungskontext: Gelesene Dateien, Tool-Ausgaben und der Gesprächsverlauf werden bei jedem Durchlauf erneut gesendet. Was Sie leeren und was Sie behalten sollten.Bild-Input wird von einem Vision-Modell abgelehntVision-Endpunkte lehnen Bilder aus vier verschiedenen Gründen ab, die fast identische Fehler erzeugen. Wie Sie sie unterscheiden, bevor Sie anfangen, neu zu kodieren.Der System-Prompt verhält sich je nach Modell unterschiedlichDie beiden vorherrschenden API-Formen platzieren System-Anweisungen unterschiedlich. Code für die eine verschlechtert sich auf der anderen stillschweigend, statt zu scheitern – und das ist schlimmer als ein Fehler.Ein 429 richtig lesen – Retry-After und die Limit-HeaderDie meisten Retry-Codes raten. Die Antwort sagt Ihnen meist genau, wie lange Sie warten sollen und welches Limit Sie erreicht haben. Wie Sie sie lesen und was zu tun ist, wenn der Header fehlt.Die Modelle eines eigenen Endpunkts erscheinen nicht in der Liste des ClientsDesktop-Clients bauen ihre Modellliste auf verschiedene Weise, und mehrere rufen /v1/models nie auf. Wie Sie erkennen, welche Art Sie haben, und was in jedem Fall zu tun ist.Leere Antwort mit finish_reason content_filterEine leere Completion mit content_filter als finish_reason heißt, dass ein Sicherheitssystem sie gestoppt hat. Wie Sie das von Abschneiden und von einem echten Fehler unterscheiden und was es Sie kostet.Die Zeitstempel im Nutzungslog passen nicht zum Zeitpunkt Ihres AufrufsEin Aufruf, der Stunden von seinem tatsächlichen Zeitpunkt entfernt erscheint, ist fast immer ein Zeitzonenunterschied und kein verlorener Eintrag. Wie Sie beides abgleichen, bevor Sie ein Abrechnungsproblem melden.Zweimal berechnet für etwas, das wie eine Anfrage aussahEin Timeout auf Client-Seite stoppt keine Arbeit, die auf dem Server schon läuft. Die übliche Form einer versehentlichen Doppelabbuchung und die zwei Änderungen, die sie verhindern.