Die Fehlerbehandlung in CometAPI ist am einfachsten, wenn Sie zwischen Problemen mit der Anfragestruktur, Authentifizierungsproblemen, Pfadfehlern und wiederholbaren Plattformfehlern unterscheiden. Verwenden Sie die Kombination aus HTTP-Status, error.code und error.message, um zu entscheiden, ob Sie die Anfrage korrigieren oder erneut senden sollten.
Schnelle Triage
Fehlerhülle
Viele CometAPI-Fehler verwenden einen Fehler-Body wie diesen:
Bei einigen Antworten bleibt code leer. Wenn der Status 500 ist, behandeln Sie error.code und error.message als das entscheidende Signal.
400 Bad Request
Ein 400 bedeutet normalerweise, dass die Validierung des Request-Bodys fehlgeschlagen ist, bevor die Anfrage normal verarbeitet werden konnte.
Häufige Ursachen:
- Fehlende Pflichtfelder wie
model
- Ungültige JSON-Struktur
- Senden eines Felds mit dem falschen Typ
- Wiederverwendung providerspezifischer Parameter, die der ausgewählte Endpoint nicht akzeptiert
Beginnen Sie mit einer minimalen, bekanntermaßen funktionierenden Anfrage und fügen Sie optionale Felder dann einzeln wieder hinzu. Vergleichen Sie die Payload mit dem Endpoint-Schema in der API-Referenz.
Verwenden Sie eine minimale Anfrage wie diese:
Ersetzen Sie your-model-id durch eine aktuelle model ID von der CometAPI Models-Seite.
Gehen Sie nicht davon aus, dass jede fehlerhafte Chat-Anfrage 400 zurückgibt. Fehlende erforderliche Chat-Felder wie messages können auch als 500 mit error.code: invalid_request erscheinen.
500 Internal Server Error
Die meisten 500-Antworten weisen auf einen Plattform- oder Providerfehler hin. Bei Chat Completions können einige fehlerhafte Anfragen auch als 500 erscheinen und dennoch error.code: invalid_request enthalten.
Ein Beispiel dafür ist eine Anfrage, in der messages fehlt:
Wenn eine 500-Antwort error.code: invalid_request enthält, behandeln Sie sie als Anfrageproblem:
- Korrigieren Sie den Request-Body.
- Vergleichen Sie die Payload mit dem Endpoint-Schema.
- Wiederholen Sie die Anfrage erst, nachdem Sie die Payload korrigiert haben.
Wenn eine 500-Antwort nicht auf eine ungültige Anfrage hinweist, behalten Sie die request id und verwenden Sie Backoff.
401 Ungültiges Token
Ein Token-Fehler sieht normalerweise so aus:
Was Sie prüfen sollten:
- Der Header muss exakt
Authorization: Bearer $COMETAPI_KEY lauten.
- Stellen Sie sicher, dass Ihre App keinen alten Schlüssel aus
.env, dem Shell-Verlauf oder einem bereitgestellten Secret-Store lädt.
- Wenn ein Schlüssel fehlschlägt und ein anderer Schlüssel bei derselben Anfrage funktioniert, behandeln Sie dies als Token-Problem und nicht als Endpoint-Problem.
403 Forbidden
403 ist in den meisten Fällen eine dieser Situationen:
- Die Anfrage wird durch eine plattformseitige Regel wie WAF-Filterung blockiert
- Das Token oder die Route darf das angeforderte Modell oder die angeforderte Request-Form nicht verwenden
- Das gewählte Modell lehnt einen der erweiterten Parameter ab, die Sie übergeben haben
Was Sie zuerst tun sollten:
- Wiederholen Sie die Anfrage mit einer sehr einfachen Textanfrage gegen ein bekanntermaßen funktionierendes Modell.
- Entfernen Sie erweiterte Felder und anbieterspezifische Parameter und fügen Sie sie dann schrittweise wieder hinzu.
- Wenn die Antwort eine request id enthält, notieren Sie sie, bevor Sie den Support kontaktieren.
Wenn in der Meldung interne Begriffe wie group oder channel erwähnt werden, behandeln Sie diese als Routing-Details und nicht als das Erste, das Sie clientseitig diagnostizieren sollten. Die praktische Lösung besteht weiterhin darin, zuerst Token, Modell und Request-Form zu validieren.
Falsche base URL oder falscher Pfad
Bei Comet kann sich ein Pfadfehler so zeigen:
- Eine Weiterleitung
- Eine Nicht-JSON-HTML-Antwort, wenn Ihr Client Weiterleitungen folgt
- Ein Parsing-Fehler in Ihrem SDK
- Eine Anfrage, die die API-Schicht nie sauber erreicht
Verwenden Sie diese base URL exakt so:
Empfohlene Prüfungen:
- Bestätigen Sie, dass die base URL
/v1 enthält.
- Bestätigen Sie, dass der Endpoint-Pfad exakt mit der Dokumentation übereinstimmt.
- Deaktivieren Sie das automatische Folgen von Weiterleitungen, während Sie Pfadprobleme debuggen.
413 Request Entity Too Large
Wenn Sie 413 sehen, behandeln Sie es zuerst als Problem mit der Request-Größe. Häufige Ursachen sind:
- Große base64-Payloads
- Zu große Bilder oder Audiodaten, die inline eingebettet sind
- Sehr große Multipart- oder JSON-Bodies
Was zu tun ist:
- Reduzieren oder komprimieren Sie angehängte Inhalte.
- Teilen Sie große Jobs in kleinere Anfragen auf.
- Gehen Sie nicht davon aus, dass nur die Länge von Klartext die Ursache ist.
429 Too Many Requests
Behandeln Sie 429 als wiederholbar:
- Verwenden Sie exponentielles Backoff mit Jitter.
- Reduzieren Sie die Burst-Concurrency.
- Lassen Sie das Request-Logging aktiviert, damit Sie sehen können, welche Route und welches Modell zuerst an die Sättigungsgrenze kommen.
Ein wiederverwendbares Retry-Muster finden Sie im Backoff-Beispiel unter Chat Completions.
503, 504 und 524
Diese Status sind serverseitige Fehler oder timeout-bezogene Fehlerklassen.
Praktische Hinweise:
503: Route oder Provider-Service vorübergehend nicht verfügbar504 und 524: timeout-bezogene Fehler zwischen der Plattform, dem Edge oder dem Provider-Service
Was zu tun ist:
- Wiederholen Sie die Anfrage mit Backoff.
- Bewahren Sie die
request id, den Endpoint, das Modell und den Zeitstempel auf.
- Wenn sich derselbe Fehler über mehrere Wiederholungen hinweg wiederholt, kontaktieren Sie den Support mit diesem Kontext.
Bevor Sie den Support kontaktieren
Erfassen Sie zuerst diese Details:
- HTTP-Methode
- Endpoint-Pfad
- Model ID
- Bereinigtes Request-Body-JSON (dies ist für die meisten API-Aufrufe der einzelne nützlichste Punkt)
- Query-Parameter, falls die fehlschlagende Anfrage diese verwendet hat
- Exakter Response-Body, falls Ihr Client ihn erfasst hat
- Vollständiger HTTP-Status
- Die genaue
error.message
- Jegliche
request id
- Ungefährer Zeitstempel
- Ob dieselbe Anfrage mit einem anderen Modell oder einem anderen Token funktioniert
Wenn die fehlschlagende Route Datei-Uploads akzeptiert (Bildbearbeitung, Audio-Upload, Videogenerierung usw.) statt eines einfachen JSON-Bodys, senden Sie die entsprechend übermittelte Payload:
- Feldnamen und Textwerte, die Sie zusammen mit der Datei gesendet haben
- Dateiname, Dateityp und ungefähre Dateigröße
- Ob die Datei direkt hochgeladen, per URL referenziert oder als base64 eingebettet wurde
Die effektivste Möglichkeit, einen Bug zu reproduzieren, ist die exakte bereinigte Request-Payload. Für die meisten API-Aufrufe bedeutet das den rohen Request-Body als JSON. Für Datei-Upload-Routen bedeutet das die Feldliste plus Datei-Metadaten.
