# API-Fehlerbehebung: häufige Fehler

_API · 4 Min. Lesezeit · Aktualisiert 2026-10-23 · https://lanachat.ai/guides/de/api-troubleshooting/_

Jeder Endpoint in der Referenz ist heute als **Planned** markiert: Es handelt sich um den veröffentlichten Vertrag, der noch nicht antwortet. Diese Seite listet die Fehler auf, die die API zurückgeben wird, damit Ihr Code sie von Anfang an verarbeiten kann.

## Lesen Sie zuerst den Fehler

Jeder Fehler antwortet mit einem 4xx- oder 5xx-Status und dem gleichen Body:

```json
{ "error": { "code": "forbidden", "message": "…" } }
```

`message` ist ein einfacher englischer Satz, der beschreibt, was schiefgelaufen ist. Protokollieren Sie ihn, verzweigen Sie Ihren Code aber anhand von `code`, niemals anhand von `message`.

## 401 unauthorized

Die API hat Ihr Token nicht akzeptiert. Prüfen Sie in dieser Reihenfolge:

1. Der Header lautet genau `Authorization: Bearer <token>`, mit dem Wort `Bearer` und einem Leerzeichen.
2. Das Token wurde vollständig kopiert. Es wird nur einmal angezeigt, wenn Sie es erstellen.
3. Das Token ist noch aktiv. In **Users › API & MCP** zeigt die Tabelle **Access tokens** das Ablaufdatum und den Status jedes Tokens, und **Show revoked tokens** listet die alten auf.
4. Wenn es abgelaufen oder widerrufen wurde, erstellen Sie ein neues (oder **Rotate** es) und aktualisieren Sie Ihre Umgebungsvariable.

## 403 forbidden

Das Token ist gültig, aber es fehlt die Berechtigung, die der Endpoint benötigt. Jeder Endpoint in der Referenz listet seine Berechtigung, z. B. `can_fan_read` oder `can_sales_read`.

1. Finden Sie die Berechtigung in der **Permission**-Spalte des Endpoints.
2. Gehen Sie in **Users › API & MCP**, klicken Sie auf **Edit** beim Token und aktivieren Sie sie.
3. Rufen Sie `GET /v1/workspace` auf: Die Antwort listet auf, was das Token darf.

Ein `403` wird auch zurückgegeben, wenn ein Token, das kein Owner-Token ist, den Header `LanaChat-Workspace` sendet. Entfernen Sie ihn.

## 429 rate_limited

Jedes Token darf 600 Anfragen pro Minute senden. Jede Antwort enthält `RateLimit-Remaining` und `RateLimit-Reset`.

- Warten Sie die Anzahl der Sekunden in `Retry-After` und versuchen Sie es dann erneut.
- Blättern Sie bei Listen mit `limit=100` statt mit einem Aufruf pro Element.
- Das Senden von Nachrichten an Fans unterliegt auch den eigenen Limits von Telegram: siehe [Telegram accounts and pools](https://lanachat.ai/guides/de/api-telegram-accounts/).

## Die anderen Codes

| Status | `code` | Was zu tun ist |
|---|---|---|
| 400 | `invalid_request` | Ein Feld fehlt oder hat das falsche Format: `message` sagt welches |
| 402 | `insufficient_balance` | Laden Sie Guthaben auf, bevor Sie kaufen |
| 404 | `not_found` | Die ID existiert nicht in diesem Workspace: prüfen Sie, ob Sie das richtige Token verwenden |
| 409 | `conflict` | Die Änderung verletzt eine Regel oder ein `Idempotency-Key` wurde mit anderem Body wiederverwendet |
| 500 | `server_error` | Später mit demselben `Idempotency-Key` erneut versuchen |

Senden Sie bei jedem `Idempotency-Key` einen `POST`: Ein erneuter Versuch führt dann nie zu doppelter Ausführung. Der Helfer im [Quick Start](https://lanachat.ai/guides/de/api-overview/) wiederholt `429` und `5xx` für Sie.

## Webhooks, die fehlschlagen

Eine Zustellung gilt als fehlgeschlagen, wenn Ihr Server nicht innerhalb von 10 Sekunden mit einem `2xx` antwortet.

1. **Antworten Sie schnell.** Geben Sie sofort `2xx` zurück, erledigen Sie die langsame Arbeit dann im Hintergrund.
2. **Prüfen Sie die Signatur am rohen Body**, bevor Sie JSON parsen. Ein geparster und neu serialisierter Body stimmt nie überein.
3. **Prüfen Sie die Uhrzeit Ihres Servers.** Ein Zeitstempel, der älter als 5 Minuten ist, wird vom Beispielcode abgelehnt, eine driftende Uhr lehnt jede Zustellung ab.
4. **Akzeptieren Sie beide `v1`-Werte** während einer Geheimnisrotation.
5. **Testen** Sie mit `POST /webhooks/{id}/test` (Planned), das ein `ping` sendet, und senden Sie eine Zustellung mit `/deliveries/{delivery_id}/retry` (Planned) erneut, sobald Sie Ihre Seite behoben haben.

Fehlgeschlagene Zustellungen werden 8-mal über etwa 24 Stunden erneut versucht. Nach 3 Tagen mit Fehlern wird der Endpoint pausiert; setzen Sie ihn mit `PATCH /webhooks/{id}` (Planned) fort. Dasselbe Ereignis kann zweimal ankommen: Ignorieren Sie Duplikate anhand der `id`. Siehe [Webhooks](https://lanachat.ai/guides/de/api-webhooks/).

## Noch immer Probleme?

Öffnen Sie die Hilfeblase unten rechts in der Console und schreiben Sie dem Team mit dem Endpoint, dem Status, dem `code` und der Uhrzeit des Aufrufs. Fügen Sie niemals das Token selbst ein. Siehe [Get help](https://lanachat.ai/guides/de/get-help/).

## Verwandte Artikel

- [LanaChat API: Schnellstart, Authentifizierung und Fehler](https://lanachat.ai/guides/de/api-overview/)
- [API: Webhooks, Events und Signaturen](https://lanachat.ai/guides/de/api-webhooks/)
- [API: Teammitglieder, Rollen und Zugriffstoken](https://lanachat.ai/guides/de/api-team/)
- [API Schnellrezepte: kopieren, einfügen, ausführen](https://lanachat.ai/guides/de/api-recipes/)