> ## 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. # Fehlercodes behandeln > Verwenden Sie diesen Leitfaden, um CometAPI-Fehlerantworten zu klassifizieren und bei häufigen Anfragefehlern Retry- oder Korrekturschritte anzuwenden. 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 | Status | Was es normalerweise bedeutet | Retry? | Erste Maßnahme | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `400` | Die Anfragevalidierung ist fehlgeschlagen, bevor die Anfrage normal verarbeitet 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. | Meistens nein | Wiederholen Sie die Anfrage mit einer funktionierenden bekannten Anfrage und entfernen Sie zuerst modellspezifische Felder. | | Path mistake | 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` with `error.code: invalid_request` | Eine fehlerhafte Anfrage wurde über eine Serverstatus-Antwort zurückgegeben. | Nein | Korrigieren Sie den Request-Body vor dem erneuten Senden. | | `500`, `503`, `504`, `524` | Plattform-, Provider- oder Timeout-Fehler. | Ja | Wiederholen Sie die Anfrage mit Backoff und behalten Sie die request id. | ## Fehlerhülle Viele CometAPI-Fehler verwenden einen Fehler-Body wie diesen: ```json theme={null} { "error": { "message": "...", "type": "comet_api_error", "param": "", "code": "invalid_request" } } ``` 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: ```json theme={null} { "model": "your-model-id", "messages": [ { "role": "user", "content": "Hello" } ] } ``` Ersetzen Sie `your-model-id` durch eine aktuelle model ID von der [CometAPI Models-Seite](/de/overview/models). 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: ```json theme={null} { "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 Request-Body. 2. Vergleichen Sie die Payload mit dem Endpoint-Schema. 3. 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: ```json theme={null} { "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 keinen alten Schlüssel aus `.env`, dem Shell-Verlauf 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 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: 1. Wiederholen Sie die Anfrage 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. 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: ```text theme={null} 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 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: 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 die Burst-Concurrency. 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](/api/text/chat). ## `503`, `504` und `524` Diese Status sind **serverseitige Fehler oder timeout-bezogene Fehlerklassen**. Praktische Hinweise: * `503`: Route oder Provider-Service vorübergehend nicht verfügbar * `504` und `524`: timeout-bezogene Fehler zwischen der Plattform, dem Edge oder dem Provider-Service Was zu tun ist: 1. Wiederholen Sie die Anfrage mit Backoff. 2. Bewahren Sie die `request id`, den Endpoint, das Modell und den Zeitstempel auf. 3. 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. Das verkürzt die Bearbeitungszeit des Supports erheblich.