# Fehlercodes

> Referenz zur Fehlerbehandlung der TBit-API

- Seite: https://tbit.app/de/docs/api/errors
- Basis-URL: `https://rest-api.tbit.app/v1`
- Authentifizierung: Header `X-API-Key` mit deinem Schlüssel in jeder Anfrage (die Beispiele lesen ihn aus der Umgebungsvariable `TBIT_API_KEY`)

Du willst wissen, warum eine WhatsApp-Nachricht nicht zugestellt wurde? Die Antwort findest du unter [WhatsApp-Zustellfehler](https://tbit.app/de/docs/whatsapp-zustellungsfehler-nachricht-nicht-angekommen).

## Format der Fehlerantwort

Alle Fehler folgen einer einheitlichen JSON-Struktur:

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

## Fehlercodes

| Status | Code | Beschreibung |
| --- | --- | --- |
| `400` | `VALIDATION_ERROR` | Ungültiger Request-Body oder ungültige Query-Parameter |
| `401` | `UNAUTHORIZED` | API-Schlüssel fehlt oder ist ungültig |
| `404` | `NOT_FOUND` | Ressource nicht gefunden oder gehört nicht zu deinem Agenten |
| `405` | `METHOD_NOT_ALLOWED` | HTTP-Methode wird von diesem Endpoint nicht unterstützt |
| `409` | `CONFLICT` | Ressource existiert bereits (z. B. Kontakt mit diesem Kanal) |
| `422` | `SEND_FAILED` | Versand der Vorlage fehlgeschlagen (z. B. kein offenes Nachrichtenfenster) |
| `429` | `RATE_LIMITED` | Rate Limit überschritten (100 Anfragen/Minute) |
| `500` | `INTERNAL_ERROR` | Unerwarteter Serverfehler |

## Rate-Limit-Header

Jede Antwort enthält Rate-Limit-Informationen in den Headern:

| Header | Beschreibung |
| --- | --- |
| `X-RateLimit-Remaining` | Verbleibende Anfragen im aktuellen Fenster |
| `X-RateLimit-Reset` | Zeitstempel (ms), wann das Fenster zurückgesetzt wird |

## Fehlerbehandlung

Best Practices für den Umgang mit API-Fehlern:

- Prüf immer den HTTP-Statuscode, bevor du den Antwort-Body auswertest
- Setz bei 429-Fehlern (Rate Limit) auf exponentielles Backoff
- Protokolliere Fehlercodes und -meldungen zum Debuggen
- Wiederhole 400- oder 401-Fehler nicht: Korrigier zuerst die Anfrage