Fehlercodes & Behandlung

Beheben Sie CometAPI-Anfragefehler mit verifizierten Hinweisen für 400-, 401- und Pfadfehler sowie praktischer Behandlung für 403-, 429- und Timeout-bezogene Fehler.

Die Behandlung von CometAPI-Fehlern ist am einfachsten, wenn Sie zwischen Anfrageproblemen, Authentifizierungsproblemen und wiederholbaren Plattformproblemen unterscheiden. Diese Seite ist der maßgebliche Leitfaden zu CometAPI-Fehlern und konzentriert sich darauf, was Sie zunächst clientseitig überprüfen können.

Dieser Leitfaden basiert auf Live-Prüfungen gegen die aktuelle CometAPI API. Wir haben 400, 401 und Pfad-/base URL-Fehler direkt verifiziert. 413, 429, 500, 503, 504 oder 524 haben wir in begrenzten Tests nicht reproduziert, daher sind die Hinweise für diese Status bewusst konservativ formuliert.

​

Schnelle Ersteinschätzung

Status	Was es normalerweise bedeutet	Wiederholen?	Erste Maßnahme
400	Die Anfragevalidierung ist fehlgeschlagen, bevor die Anfrage erfolgreich weitergeleitet wurde.	Nein	Validieren Sie model, messages, die JSON-Struktur und die Feldtypen.
401	Der API-Schlüssel fehlt, ist fehlerhaft formatiert oder ungültig.	Nein	Prüfen Sie Authorization: Bearer <COMETAPI_KEY>.
403	Der Zugriff wurde blockiert oder die aktuelle Anfrage war nicht zulässig.	In der Regel nein	Wiederholen Sie den Versuch mit einer bekanntermaßen funktionierenden Anfrage und entfernen Sie zuerst modellspezifische Felder.
Pfadfehler	Falsche base URL oder falscher Endpoint-Pfad. Bei Comet kann dies als 301-Weiterleitung oder HTML erscheinen, nicht als sauberes JSON-404.	Nein	Verwenden Sie exakt https://api.cometapi.com/v1 und deaktivieren Sie beim Debuggen das automatische Folgen von Weiterleitungen.
429	Rate Limiting oder vorübergehende Auslastung.	Ja	Verwenden Sie exponentielles Backoff mit Jitter.
500, 503, 504, 524	Plattform- oder Timeout-bezogener Fehler.	Ja	Wiederholen Sie den Versuch mit Backoff und bewahren Sie die Request-ID auf.

​

Fehler-Envelope

Der aktuelle JSON-Fehler-Envelope, den CometAPI zurückgibt, sieht so aus:

{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}

Viele Live-Fehlermeldungen enthalten außerdem eine request id innerhalb von error.message. Speichern Sie diesen Wert, wenn Sie Support benötigen.

​

400 Bad Request

Was wir bei der Live-API beobachtet haben, wenn model weggelassen wurde:

{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}

In der Praxis bedeutet 400 normalerweise, dass der Anfrage-Body die Validierung nicht bestanden hat, bevor die Plattform ihn an den Modellanbieter weiterleiten konnte.

Häufige Ursachen:

• Fehlende Pflichtfelder wie model oder messages
• Ungültige JSON-Struktur
• Senden eines Felds mit dem falschen Typ
• Wiederverwendung anbieterspezifischer Parameter, die der ausgewählte Endpoint nicht akzeptiert

Was zu tun ist:

1. Beginnen Sie mit einer minimalen, bekanntermaßen funktionierenden Anfrage.
2. Fügen Sie optionale Felder nacheinander wieder hinzu.
3. Vergleichen Sie den Anfrage-Body mit dem Endpoint-Schema in der API-Referenz.

Minimales, bekanntermaßen funktionierendes Beispiel:

{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}

Ersetzen Sie your-model-id durch eine aktuelle Modell-ID von der CometAPI Models page.

​

401 Invalid Token

Was wir bei der Live-API mit einem ungültigen Schlüssel beobachtet haben:

{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}

Was Sie prüfen sollten:

1. Der Header muss exakt Authorization: Bearer <COMETAPI_KEY> lauten.
2. Stellen Sie sicher, dass Ihre App nicht einen alten Schlüssel aus .env, der Shell-Historie oder einem bereitgestellten Secret-Store lädt.
3. Wenn ein Schlüssel fehlschlägt und ein anderer Schlüssel bei derselben Anfrage funktioniert, behandeln Sie dies als Token-Problem, nicht als Endpoint-Problem.

​

403 Forbidden

Wir konnten in begrenzten Tests keinen stabilen 403 reproduzieren, daher sollte eine einzelne alte Nachrichtenvorlage nicht als die ganze Erklärung betrachtet werden.

In der aktuellen Comet-Dokumentation wird 403 am häufigsten als eine der folgenden Situationen beschrieben:

• Die Anfrage wird durch eine plattformseitige Regel wie WAF-Filterung blockiert
• Der token oder die Route darf das angeforderte model oder die angeforderte Anfrageform nicht verwenden
• Das gewählte model lehnt einen der erweiterten Parameter ab, die du übergeben hast

Was du zuerst tun solltest:

1. Wiederhole die Anfrage mit einer sehr einfachen Textanfrage gegen ein bekannt funktionierendes model.
2. Entferne erweiterte Felder und providerspezifische Parameter und füge sie dann schrittweise wieder hinzu.
3. Falls die Antwort eine request id enthält, bewahre sie auf, bevor du den Support kontaktierst.

Wenn die Nachricht interne Begriffe wie group oder channel erwähnt, betrachte diese als Routing-Details und nicht als das Erste, was du clientseitig diagnostizieren solltest. Die praktische Lösung besteht weiterhin darin, zuerst token, model und Anfrageform zu prüfen.

​

Falsche Base URL oder falscher Pfad

Dies ist der Bereich, in dem die alte Seite am wenigsten präzise war.

Bei Live-Prüfungen gegen die aktuellen Comet-Endpunkte:

• Das Senden an https://api.cometapi.com/chat/completions lieferte einen 301-Redirect zu https://www.cometapi.com/chat/completions
• Das Senden an eine erfundene API-Route wie https://api.cometapi.com/v1/not-a-real-endpoint lieferte ebenfalls einen 301-Redirect zu https://www.cometapi.com/v1/not-a-real-endpoint

Das bedeutet, dass sich ein Pfadfehler wie folgt zeigen kann:

• Ein Redirect
• Eine nicht-JSON-HTML-Antwort, wenn dein Client Redirects folgt
• Ein Parsing-Fehler in deinem SDK
• Eine Anfrage, die die API-Schicht nie sauber erreicht

Verwende genau diese Base URL:

https://api.cometapi.com/v1

Empfohlene Prüfungen:

1. Bestätige, dass die Base URL /v1 enthält.
2. Bestätige, dass der Endpunktpfad exakt mit der Dokumentation übereinstimmt.
3. Deaktiviere beim Debugging von Pfadproblemen das automatische Folgen von Redirects.

​

413 Request Entity Too Large

Wir konnten 413 in einem begrenzten Test nicht reproduzieren, selbst nicht mit einem übergroßen 8 MiB-JSON-Request-Body, daher war die alte Erklärung, dass der prompt zu lang sei, zu eng gefasst.

Wenn du doch ein 413 siehst, behandle es zuerst als Problem mit der Anfragegröße. Häufige Ursachen sind:

• Große base64-Payloads
• Übergroße Bilder oder Audiodaten, die inline eingebettet sind
• Sehr große Multipart- oder JSON-Bodies

Was du tun solltest:

1. Reduziere oder komprimiere angehängte Inhalte.
2. Teile große Jobs in kleinere Anfragen auf.
3. Gehe nicht davon aus, dass nur die Länge von Klartext die Ursache ist.

​

429 Too Many Requests

Wir konnten 429 während einer begrenzten Parallelitätsprüfung mit 24 parallelen GET /v1/models-Anfragen nicht reproduzieren, daher hängt der genaue Schwellenwert offensichtlich von Route, model und dem aktuellen Plattformzustand ab.

Behandle 429 als wiederholbar:

1. Verwende exponentielles Backoff mit Jitter.
2. Reduziere Burst-Parallelität.
3. Lasse die Anfrageprotokollierung aktiviert, damit du sehen kannst, welche Route und welches model zuerst an die Auslastungsgrenze kommen.

Ein wiederverwendbares Retry-Muster findest du im Backoff-Beispiel unter Chat Completions.

​

500, 503, 504, und 524

Wir konnten diese Statuscodes in begrenzten Tests nicht reproduzieren. Sie sollten als serverseitige oder Timeout-bezogene Fehler dokumentiert werden, nicht als Fehler von Nutzerinnen und Nutzern.

Praktische Hinweise:

• 500: interner Plattform- oder providerseitiger Fehler
• 503: Route oder Provider-Dienst vorübergehend nicht verfügbar
• 504 und 524: Timeout-bezogene Fehler zwischen der Plattform, dem Edge oder dem Provider-Dienst

Was du tun solltest:

1. Wiederhole die Anfrage mit Backoff.
2. Bewahre request id, Endpunkt, model und Zeitstempel auf.
3. Wenn derselbe Fehler sich über mehrere Wiederholungen hinweg wiederholt, kontaktiere den Support mit diesem Kontext.

​

Bevor Sie den Support kontaktieren

Erfassen Sie zuerst diese Details:

• HTTP-Methode
• Endpoint-Pfad
• Modellname
• Bereinigter JSON-Request-Body (dies ist für die meisten API-Aufrufe der einzelne nützlichste Punkt)
• Query-Parameter, falls die fehlschlagende Anfrage sie 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

Der schnellste Weg, einen Bug zu reproduzieren, ist die exakt bereinigte Request-Payload. Für die meisten API-Aufrufe bedeutet das den rohen JSON-Request-Body. Für Datei-Upload-Routen bedeutet das die Feldliste plus Datei-Metadaten.

Das verkürzt die Bearbeitungszeit des Supports erheblich.