Zum Hauptinhalt springen

Documentation Index

Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt

Use this file to discover all available pages before exploring further.

Die Fehlerbehandlung in CometAPI ist am einfachsten, wenn Sie Probleme mit der Anfragestruktur, Authentifizierungsprobleme, Pfadfehler und wiederholbare Plattformfehler voneinander trennen. Verwenden Sie die Kombination aus HTTP-Status, error.code und error.message, um zu entscheiden, ob Sie die Anfrage korrigieren oder erneut versuchen sollten.

​
Schnelle Triage

StatusWas es normalerweise bedeutetErneut versuchen?Erste Maßnahme
400Die Validierung der Anfrage ist fehlgeschlagen, bevor die Anfrage normal verarbeitet wurde.NeinPrüfen Sie model, messages, die JSON-Struktur und die Feldtypen.
401Der API-Schlüssel fehlt, ist fehlerhaft formatiert oder ungültig.NeinPrüfen Sie Authorization: Bearer <COMETAPI_KEY>.
403Der Zugriff wurde blockiert oder die aktuelle Anfrage war nicht zulässig.Meistens neinWiederholen Sie den Versuch mit einer bekanntermaßen funktionierenden Anfrage und entfernen Sie zuerst modellspezifische Felder.
Path mistakeFalsche base URL oder falscher Endpoint-Pfad. Bei Comet kann dies als 301-Weiterleitung oder HTML erscheinen, nicht als saubere JSON-404.NeinVerwenden Sie exakt https://api.cometapi.com/v1 und deaktivieren Sie beim Debuggen das automatische Folgen von Weiterleitungen.
429Rate limiting oder vorübergehende Überlastung.JaVerwenden Sie exponentielles Backoff mit Jitter.
500 with error.code: invalid_requestEine fehlerhafte Anfrage wurde über eine Serverstatus-Antwort zurückgegeben.NeinKorrigieren Sie den Anfrage-Body, bevor Sie es erneut versuchen.
500, 503, 504, 524Plattform-, Anbieter- oder Timeout-Fehler.JaVersuchen Sie es mit Backoff erneut und behalten Sie die request id bei.

​
Error envelope

Viele CometAPI-Fehler verwenden einen Fehler-Body wie diesen: 
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
Bei manchen Antworten bleibt code leer. Wenn der Status 500 ist, behandeln Sie error.code und error.message als ausschlaggebendes Signal.

​
400 Bad Request

Ein 400 bedeutet in der Regel, dass die Validierung des Anfrage-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 anbieterspezifischer Parameter, die der ausgewählte Endpoint nicht akzeptiert
Beginnen Sie mit einer minimalen, bekanntermaßen funktionierenden Anfrage und fügen Sie dann optionale Felder nacheinander wieder hinzu. Vergleichen Sie die Payload mit dem Endpoint-Schema in der API-Referenz. Verwenden Sie eine minimale Anfrage wie diese: 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
Ersetzen Sie your-model-id durch eine aktuelle model ID von der CometAPI Models page. Gehen Sie nicht davon aus, dass jede fehlerhafte Chat-Anfrage ein 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 Anbieterfehler hin. Bei Chat Completions können einige fehlerhafte Anfragen ebenfalls als 500 erscheinen und dennoch error.code: invalid_request enthalten. Ein Beispiel dafür ist eine Anfrage, bei der messages fehlt: 
{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
Wenn eine 500-Antwort error.code: invalid_request enthält, behandeln Sie sie als Anfrageproblem:
  1. Korrigieren Sie den Anfrage-Body.
  2. Vergleichen Sie die Payload mit dem Endpoint-Schema.
  3. Versuchen Sie es erst nach der Korrektur der Payload erneut.
Wenn eine 500-Antwort nicht auf eine ungültige Anfrage hinweist, behalten Sie die request id bei und verwenden Sie Backoff.

​
401 Invalid Token

Ein Token-Fehler sieht normalerweise so aus: 
{
	"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 ein Token-Problem, nicht als ein 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
  • Der Token oder die Route darf das angeforderte Modell oder die Request-Form nicht verwenden
  • Das gewählte Modell lehnt einen der erweiterten Parameter ab, die Sie übergeben haben
Was Sie zuerst tun sollten:
  1. Wiederholen Sie den Versuch mit einer sehr einfachen Textanfrage gegen ein bekanntermaßen funktionierendes Modell.
  2. Entfernen Sie erweiterte Felder und anbieterspezifische Parameter und fügen Sie sie dann schrittweise wieder hinzu.
  3. Falls die Antwort eine request id enthält, bewahren Sie diese auf, bevor Sie den Support kontaktieren.
Wenn die Nachricht interne Begriffe wie group oder channel erwähnt, behandeln Sie diese als Routing-Details und nicht als das Erste, was 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 wie folgt zeigen:
  • Eine Weiterleitung
  • Eine Nicht-JSON-HTML-Antwort, wenn Ihr Client Weiterleitungen folgt
  • Ein Parsing-Fehler innerhalb Ihres SDK
  • Eine Anfrage, die die API-Schicht nie sauber erreicht
Verwenden Sie genau diese base URL: 
https://api.cometapi.com/v1
Empfohlene Prüfungen:
  1. Bestätigen Sie, dass die base URL /v1 enthält.
  2. Bestätigen Sie, dass der Endpoint-Pfad exakt mit der Dokumentation übereinstimmt.
  3. Deaktivieren Sie die automatische Weiterleitungsverfolgung, während Sie Pfadprobleme debuggen.

​
413 Request Entity Too Large

Wenn Sie 413 sehen, behandeln Sie es zuerst als ein Problem mit der Anfragegröße. Häufige Ursachen sind:
  • Große base64-Payloads
  • Zu große Bilder oder Audiodateien, die inline eingebettet sind
  • Sehr große Multipart- oder JSON-Bodys
Was zu tun ist:
  1. Reduzieren oder komprimieren Sie angehängte Inhalte.
  2. Teilen Sie große Jobs in kleinere Anfragen auf.
  3. Gehen Sie nicht davon aus, dass nur die Länge von Klartext die Ursache ist.

​
429 Too Many Requests

Behandeln Sie 429 als wiederholbar:
  1. Verwenden Sie exponentielles Backoff mit Jitter.
  2. Reduzieren Sie Burst-Konkurrenz.
  3. 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 oder timeoutbezogene Fehler. Praktische Hinweise:
  • 503: Route oder Provider-Dienst vorübergehend nicht verfügbar
  • 504 und 524: timeoutbezogene Fehler zwischen der Plattform, dem Edge oder dem Provider-Dienst
Was zu tun ist:
  1. Wiederholen Sie den Versuch mit Backoff.
  2. Halten Sie die request id, den Endpoint, das Modell und den Zeitstempel fest.
  3. Wenn derselbe Fehler über mehrere Retries hinweg wiederholt auftritt, kontaktieren Sie den Support mit diesem Kontext.

​
Bevor Sie den Support kontaktieren

Erfassen Sie zuerst diese Details:
  • HTTP-Methode
  • Endpoint-Pfad
  • Model ID
  • Bereinigtes JSON des Request-Bodys (das ist für die meisten API-Aufrufe der nützlichste Einzelpunkt)
  • Query-Parameter, falls die fehlgeschlagene Anfrage diese verwendet hat
  • Exakter Response-Body, falls Ihr Client ihn erfasst hat
  • Vollständiger HTTP-Status
  • Die genaue error.message
  • Jede request id
  • Ungefährer Zeitstempel
  • Ob dieselbe Anfrage mit einem anderen Modell oder einem anderen Token funktioniert
Wenn die fehlgeschlagene 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 Methode, 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.