De foutafhandeling van CometAPI is het eenvoudigst wanneer je problemen met de request-structuur, auth-problemen, padfouten en retrybare platformstoringen van elkaar scheidt. Gebruik de combinatie van HTTP-status, error.code en error.message om te bepalen of je de request moet herstellen of opnieuw moet proberen.
Snelle triage
Error envelope
Veel CometAPI-fouten gebruiken een foutbody zoals deze:
Bij sommige responses blijft code leeg. Wanneer de status 500 is, behandel error.code en error.message dan als het doorslaggevende signaal.
400 Bad Request
Een 400 betekent meestal dat de request body de validatie niet heeft doorstaan voordat de request normaal kon worden verwerkt.
Veelvoorkomende oorzaken:
- Ontbrekende verplichte velden zoals
model
- Ongeldige JSON-structuur
- Een veld verzenden met het verkeerde type
- Providerspecifieke parameters hergebruiken die het geselecteerde endpoint niet accepteert
Begin met een minimale, bekende goed werkende request en voeg daarna optionele velden één voor één weer toe. Vergelijk de payload met het endpointschema in de API-referentie.
Gebruik een minimale request zoals deze:
Vervang your-model-id door een actuele model ID van de CometAPI Models page.
Ga er niet van uit dat elke onjuist geformatteerde chatrequest een 400 retourneert. Ontbrekende verplichte chatvelden zoals messages kunnen ook verschijnen als 500 met error.code: invalid_request.
500 Internal Server Error
De meeste 500-responses duiden op een platform- of providerfout. Voor Chat Completions kunnen sommige onjuist geformatteerde requests ook verschijnen als 500 terwijl ze nog steeds error.code: invalid_request bevatten.
Een voorbeeld is een request waarin messages ontbreekt:
Als een 500-response error.code: invalid_request heeft, behandel dit dan als een requestprobleem:
- Herstel de request body.
- Vergelijk de payload met het endpointschema.
- Probeer pas opnieuw nadat je de payload hebt gecorrigeerd.
Als een 500-response niet wijst op een ongeldige request, bewaar dan het request id en gebruik backoff.
401 Ongeldige token
Een tokenfout ziet er meestal zo uit:
Wat je moet controleren:
- De header moet exact
Authorization: Bearer $COMETAPI_KEY zijn.
- Controleer of je app niet een oude sleutel laadt uit
.env, shell history of een gedeployde secret store.
- Als de ene sleutel faalt en een andere sleutel werkt voor dezelfde request, behandel dit dan als een tokenprobleem, niet als een endpointprobleem.
403 Forbidden
403 is meestal een van deze situaties:
- De request wordt geblokkeerd door een platformregel, zoals WAF-filtering
- De token of route mag het gevraagde model of de requestvorm niet gebruiken
- Het gekozen model wijst een van de geavanceerde parameters af die je hebt meegegeven
Wat je eerst moet doen:
- Probeer opnieuw met een zeer eenvoudige tekstrequest tegen een model waarvan bekend is dat het werkt.
- Verwijder geavanceerde velden en provider-specifieke parameters, en voeg ze daarna geleidelijk weer toe.
- Als de response een request id bevat, bewaar die dan voordat je contact opneemt met support.
Als het bericht interne termen noemt zoals group of channel, beschouw die dan als routingdetails, niet als het eerste om vanaf de clientkant te diagnosticeren. De praktische oplossing blijft om eerst de token, het model en de requestvorm te valideren.
Verkeerde base URL of verkeerd pad
Bij Comet kan een fout in het pad zichtbaar worden als:
- Een redirect
- Een niet-JSON HTML-response als je client redirects volgt
- Een parsing error in je SDK
- Een request die de API-laag nooit netjes bereikt
Gebruik exact deze base URL:
Aanbevolen controles:
- Controleer of de base URL
/v1 bevat.
- Controleer of het endpointpad exact overeenkomt met de documentatie.
- Schakel automatisch redirects volgen uit terwijl je padproblemen debugt.
413 Request Entity Too Large
Als je 413 ziet, behandel dit dan eerst als een probleem met de requestgrootte. Veelvoorkomende oorzaken zijn:
- Grote base64-payloads
- Te grote afbeeldingen of audio die inline zijn ingesloten
- Zeer grote multipart- of JSON-bodies
Wat je moet doen:
- Verklein of comprimeer bijgevoegde content.
- Splits grote taken op in kleinere requests.
- Ga er niet van uit dat alleen de lengte van platte tekst de oorzaak is.
429 Too Many Requests
Behandel 429 als opnieuw te proberen:
- Gebruik exponential backoff met jitter.
- Verminder burst concurrency.
- Laat request logging ingeschakeld zodat je kunt zien welke route en welk model als eerste verzadigd raken.
Voor een herbruikbaar retry-patroon, zie het backoff-voorbeeld op Chat Completions.
503, 504 en 524
Deze statussen zijn server-side of timeout-gerelateerde fouten.
Praktische richtlijnen:
503: route of provider service tijdelijk niet beschikbaar504 en 524: timeout-gerelateerde fouten tussen het platform, edge of provider service
Wat je moet doen:
- Probeer opnieuw met backoff.
- Bewaar de
request id, endpoint, model en timestamp.
- Als dezelfde fout zich over meerdere retries blijft herhalen, neem dan contact op met support met die context.
Leg deze gegevens eerst vast:
- HTTP-methode
- Endpoint-pad
- Model ID
- Geschoonde request body JSON (dit is voor de meeste API-calls het meest nuttige onderdeel)
- Query-parameters als de mislukte request die gebruikte
- Exacte response body als je client die heeft vastgelegd
- Volledige HTTP-status
- De exacte
error.message
- Elke
request id
- Geschatte tijdstempel
- Of dezelfde request werkt met een ander model of een andere token
Als de mislukte route bestandsuploads accepteert (beeldbewerking, audio-upload, videogeneratie, enz.) in plaats van een gewone JSON body, stuur dan de equivalente ingediende payload:
- Veldnamen en tekstwaarden die je samen met het bestand hebt verstuurd
- Bestandsnaam, bestandstype en geschatte bestandsgrootte
- Of het bestand direct is geüpload, via URL is verwezen, of als base64 is ingesloten
De meest effectieve manier om een bug te reproduceren is de exacte geschoonde request payload. Voor de meeste API-calls betekent dat de ruwe request body JSON. Voor routes met bestandsuploads betekent dat de lijst met velden plus bestandsmetadata.
