API-Fehlerbehebung: häufige Fehler

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:

{ "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.

Die anderen Codes #

Senden Sie bei jedem Idempotency-Key einen POST: Ein erneuter Versuch führt dann nie zu doppelter Ausführung. Der Helfer im Quick Start 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.

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.