Risoluzione problemi API: errori comuni
Ogni endpoint nella reference è oggi contrassegnato come Planned: è il contratto pubblicato ma non risponde ancora. Questa pagina elenca gli errori che l’API restituirà, così il tuo codice potrà gestirli fin dal primo giorno.
Leggi prima l’errore #
Ogni errore risponde con uno status 4xx o 5xx e lo stesso corpo:
{ "error": { "code": "forbidden", "message": "…" } }message è una frase in inglese semplice che spiega cosa è andato storto. Registrala, ma fai il branching del codice sul code, mai sul message.
401 unauthorized #
L’API non ha accettato il tuo token. Controlla, in quest’ordine:
- L’header è esattamente
Authorization: Bearer <token>, con la parolaBearere uno spazio. - Il token è stato copiato per intero. Viene mostrato solo una volta, quando lo crei.
- Il token è ancora attivo. In Users › API & MCP, la tabella Access tokens mostra scadenza e stato di ogni token, e Show revoked tokens elenca quelli vecchi.
- Se è scaduto o revocato, creane uno nuovo (o Rotate quello esistente) e aggiorna la variabile d’ambiente.
403 forbidden #
Il token è valido ma manca il permesso richiesto dall’endpoint. Ogni endpoint nella reference indica il permesso, come can_fan_read o can_sales_read.
- Trova il permesso nella colonna Permission dell’endpoint.
- In Users › API & MCP, clicca Edit sul token e selezionalo.
- Chiama
GET /v1/workspace: la risposta elenca cosa può fare il token.
Un 403 arriva anche se un token non owner invia l’header LanaChat-Workspace. Rimuovilo.
429 rate_limited #
Ogni token può inviare 600 richieste al minuto. Ogni risposta include RateLimit-Remaining e RateLimit-Reset.
- Aspetta i secondi indicati in
Retry-After, poi riprova. - Scorri le liste con
limit=100invece di una chiamata per ogni elemento. - L’invio di messaggi ai fans è soggetto anche ai limiti di Telegram: vedi Telegram accounts and pools.
Gli altri codici #
| Status | code | Cosa fare |
|---|---|---|
| 400 | invalid_request | Un campo manca o ha formato errato: message indica quale |
| 402 | insufficient_balance | Ricarica prima di acquistare |
| 404 | not_found | L’id non esiste in questo workspace: verifica di usare il token giusto |
| 409 | conflict | La modifica viola una regola, o un Idempotency-Key è stato riutilizzato con un body diverso |
| 500 | server_error | Riprova più tardi con lo stesso Idempotency-Key |
Invia un Idempotency-Key ad ogni POST: così un retry non esegue due volte l’operazione. L’helper in the quick start ritenta per te i codici 429 e 5xx.
Webhook che falliscono #
Una consegna è fallita se il tuo server non risponde con un 2xx entro 10 secondi.
- Rispondi velocemente. Restituisci subito
2xx, poi esegui il lavoro lento in background. - Controlla la firma sul corpo raw, prima di qualsiasi parsing JSON. Un corpo parsato e riserializzato non corrisponde mai.
- Controlla l’orologio del server. Un timestamp più vecchio di 5 minuti viene rifiutato dal codice di esempio, quindi un orologio sfasato rifiuta tutte le consegne.
- Accetta entrambi i valori
v1durante una rotazione del segreto. - Testa con
POST /webhooks/{id}/test(Planned), che invia unping, e reinvia una consegna con/deliveries/{delivery_id}/retry(Planned) una volta sistemato il tuo lato.
Le consegne fallite vengono ritentate 8 volte in circa 24 ore. Dopo 3 giorni di fallimenti l’endpoint viene messo in pausa; riattivalo con PATCH /webhooks/{id} (Planned). Lo stesso evento può arrivare due volte: ignora i duplicati tramite id. Vedi Webhooks.
Ancora bloccato? #
Apri la bolla di aiuto in basso a destra nella Console e scrivi al team indicando endpoint, status, code e orario della chiamata. Mai incollare il token. Vedi Get help.