# Foutcodes

> Overzicht van foutafhandeling voor de TBit API

- Pagina: https://tbit.app/nl/docs/api/errors
- Basis-URL: `https://rest-api.tbit.app/v1`
- Authenticatie: header `X-API-Key` met je sleutel bij elk verzoek (de voorbeelden lezen hem uit de omgevingsvariabele `TBIT_API_KEY`)

Wil je weten waarom een WhatsApp-bericht niet is bezorgd? Lees [Bezorgfouten op WhatsApp (in het Spaans)](https://tbit.app/es/docs/errores-de-entrega-whatsapp).

## Formaat van een foutresponse

Alle fouten volgen een vaste JSON-structuur:

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Activity not found"
  }
}
```

## Foutcodes

| Status | Code | Beschrijving |
| --- | --- | --- |
| `400` | `VALIDATION_ERROR` | Ongeldige request-body of queryparameters |
| `401` | `UNAUTHORIZED` | API-sleutel ontbreekt of is ongeldig |
| `404` | `NOT_FOUND` | Resource niet gevonden of hoort niet bij je agent |
| `405` | `METHOD_NOT_ALLOWED` | HTTP-methode niet ondersteund voor dit endpoint |
| `409` | `CONFLICT` | Resource bestaat al (bijv. een contact met dit kanaal) |
| `422` | `SEND_FAILED` | Template versturen mislukt (bijv. geen berichtvenster) |
| `429` | `RATE_LIMITED` | Rate limit overschreden (100 verzoeken/minuut) |
| `500` | `INTERNAL_ERROR` | Onverwachte serverfout |

## Rate-limit-headers

Elke response bevat in de headers informatie over de rate limit:

| Header | Beschrijving |
| --- | --- |
| `X-RateLimit-Remaining` | Resterende verzoeken in het huidige venster |
| `X-RateLimit-Reset` | Tijdstempel (ms) waarop het venster wordt gereset |

## Fouten afhandelen

Best practices voor het afhandelen van API-fouten:

- Controleer altijd de HTTP-statuscode voordat je de response-body parseert
- Gebruik exponential backoff bij 429-fouten (rate limit)
- Log foutcodes en -berichten om te debuggen
- Probeer 400- of 401-fouten niet opnieuw: corrigeer eerst het verzoek