# Risoluzione problemi API: errori comuni

_API · 4 min di lettura · Aggiornato 2026-10-23 · https://lanachat.ai/guides/it/api-troubleshooting/_

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:

```json
{ "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:

1. L’header è esattamente `Authorization: Bearer <token>`, con la parola `Bearer` e uno spazio.
2. Il token è stato copiato per intero. Viene mostrato solo una volta, quando lo crei.
3. 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.
4. 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`.

1. Trova il permesso nella colonna **Permission** dell’endpoint.
2. In **Users › API & MCP**, clicca **Edit** sul token e selezionalo.
3. 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=100` invece di una chiamata per ogni elemento.
- L’invio di messaggi ai fans è soggetto anche ai limiti di Telegram: vedi [Telegram accounts and pools](https://lanachat.ai/guides/it/api-telegram-accounts/).

## 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](https://lanachat.ai/guides/it/api-overview/) 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.

1. **Rispondi velocemente.** Restituisci subito `2xx`, poi esegui il lavoro lento in background.
2. **Controlla la firma sul corpo raw**, prima di qualsiasi parsing JSON. Un corpo parsato e riserializzato non corrisponde mai.
3. **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.
4. **Accetta entrambi i valori `v1`** durante una rotazione del segreto.
5. **Testa** con `POST /webhooks/{id}/test` (Planned), che invia un `ping`, 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](https://lanachat.ai/guides/it/api-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](https://lanachat.ai/guides/it/get-help/).

## Articoli correlati

- [API LanaChat: avvio rapido, autenticazione ed errori](https://lanachat.ai/guides/it/api-overview/)
- [API: webhook, eventi e firme](https://lanachat.ai/guides/it/api-webhooks/)
- [API: membri del team, ruoli e token di accesso](https://lanachat.ai/guides/it/api-team/)
- [Ricette rapide API: copia, incolla, esegui](https://lanachat.ai/guides/it/api-recipes/)