> ## 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.

# Errorcodes afhandelen

> Gebruik deze gids om CometAPI-foutreacties te classificeren en retry- of herstelstappen toe te passen voor veelvoorkomende requestfouten.

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

| Status                                   | Wat het meestal betekent                                                                                                                 | Retry?       | Eerste actie                                                                                                  |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- |
| `400`                                    | Requestvalidatie is mislukt voordat de request normaal werd verwerkt.                                                                    | Nee          | Valideer `model`, `messages`, JSON-structuur en veldtypen.                                                    |
| `401`                                    | API key ontbreekt, is ongeldig geformatteerd of is ongeldig.                                                                             | Nee          | Controleer `Authorization: Bearer $COMETAPI_KEY`.                                                             |
| `403`                                    | Toegang is geblokkeerd of de huidige request was niet toegestaan.                                                                        | Meestal niet | Probeer opnieuw met een bekende goed werkende request en verwijder eerst modelspecifieke velden.              |
| Path mistake                             | Verkeerde base URL of verkeerd endpointpad. Bij Comet kan dit verschijnen als een `301`-redirect of HTML, niet als een nette JSON-`404`. | Nee          | Gebruik exact `https://api.cometapi.com/v1` en schakel automatisch redirects volgen uit tijdens het debuggen. |
| `429`                                    | Rate limiting of tijdelijke verzadiging.                                                                                                 | Ja           | Gebruik exponentiële backoff met jitter.                                                                      |
| `500` with `error.code: invalid_request` | Een onjuist geformatteerde request kwam naar voren via een server-statusreactie.                                                         | Nee          | Herstel de request body voordat je opnieuw probeert.                                                          |
| `500`, `503`, `504`, `524`               | Platform-, provider- of timeoutfout.                                                                                                     | Ja           | Probeer opnieuw met backoff en bewaar het request id.                                                         |

## Error envelope

Veel CometAPI-fouten gebruiken een foutbody zoals deze:

```json theme={null}
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
```

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:

```json theme={null}
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
```

Vervang `your-model-id` door een actuele model ID van de [CometAPI Models page](/nl/overview/models).

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:

```json theme={null}
{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
```

Als een `500`-response `error.code: invalid_request` heeft, behandel dit dan als een requestprobleem:

1. Herstel de request body.
2. Vergelijk de payload met het endpointschema.
3. 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:

```json theme={null}
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
```

Wat je moet controleren:

1. De header moet exact `Authorization: Bearer $COMETAPI_KEY` zijn.
2. Controleer of je app niet een oude sleutel laadt uit `.env`, shell history of een gedeployde secret store.
3. 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:

1. Probeer opnieuw met een zeer eenvoudige tekstrequest tegen een model waarvan bekend is dat het werkt.
2. Verwijder geavanceerde velden en provider-specifieke parameters, en voeg ze daarna geleidelijk weer toe.
3. Als de response een request id bevat, bewaar die dan voordat je contact opneemt met support.

<Warning>
  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.
</Warning>

## 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:

```text theme={null}
https://api.cometapi.com/v1
```

Aanbevolen controles:

1. Controleer of de base URL `/v1` bevat.
2. Controleer of het endpointpad exact overeenkomt met de documentatie.
3. 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:

1. Verklein of comprimeer bijgevoegde content.
2. Splits grote taken op in kleinere requests.
3. 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:

1. Gebruik exponential backoff met jitter.
2. Verminder burst concurrency.
3. 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](/api/text/chat).

## `503`, `504` en `524`

Deze statussen zijn **server-side of timeout-gerelateerde fouten**.

Praktische richtlijnen:

* `503`: route of provider service tijdelijk niet beschikbaar
* `504` en `524`: timeout-gerelateerde fouten tussen het platform, edge of provider service

Wat je moet doen:

1. Probeer opnieuw met backoff.
2. Bewaar de `request id`, endpoint, model en timestamp.
3. Als dezelfde fout zich over meerdere retries blijft herhalen, neem dan contact op met support met die context.

## Voordat je contact opneemt met support

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

<Warning>
  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.
</Warning>

Dit verkort de doorlooptijd van support aanzienlijk.