> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.userbot.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.userbot.ai/_mcp/server.

# Codici di errore

Quando una richiesta REST fallisce, l'API restituisce uno status HTTP e un body JSON con dettagli sull'errore. Interpretare correttamente lo status ti aiuta a capire se il problema è temporaneo (ritenta), di configurazione (correggi credenziali o parametri) o lato server (contatta il supporto).

Questa pagina elenca gli status più comuni e come gestirli. Per messaggi di errore specifici per endpoint (es. "Invalid state value"), consulta la [REST API](/api-reference) — ogni operazione documenta i suoi errori possibili.

## Status HTTP comuni

| Status | Significato                                                                      | Azione consigliata                                                                                 |
| ------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| 200    | Successo                                                                         | —                                                                                                  |
| 201    | Risorsa creata / risposta dal bot                                                | —                                                                                                  |
| 400    | Richiesta malformata — body JSON invalido o parametri mancanti                   | Controlla il body e i campi obbligatori; non ritentare senza correggere                            |
| 401    | Non autorizzato — token mancante, scaduto o firma webhook non valida             | Verifica header `Authorization` o implementazione HMAC; vedi [Autenticazione](/api-autenticazione) |
| 403    | Forbidden — token valido ma operazione non consentita per l'account              | Contatta il tuo referente Userbot per verificare l'accesso alle API                                |
| 404    | Risorsa non trovata — `session_id` o Secret Key (`bot_key`) errata o inesistente | Controlla che gli identificatori siano corretti e che la risorsa esista                            |
| 429    | Troppe richieste — limite di frequenza superato                                  | Attendi e ritenta con backoff, rispettando `Retry-After`; vedi [Rate limiting](/api-rate-limiting) |
| 500    | Errore interno del server — timeout attesa risposta bot o failure del motore     | Ritenta con backoff; se persiste, segnala al supporto con timestamp e `session`                    |

## Formato del body errore

Le risposte di errore sono in JSON. Il formato esatto può variare per endpoint, ma tipicamente include un messaggio descrittivo che aiuta il debug. Logga status e body (senza token o PII) per diagnosticare problemi in produzione.

## Errori per endpoint

Alcuni endpoint restituiscono messaggi specifici oltre allo status generico:

* **"Invalid state value"** — valore di `state` non supportato in `PATCH` conversazione
* **"At least one of message or beforeMessage must be provided"** — body messaggio incompleto
* Altri casi documentati nella [REST API](/api-reference) per ogni operazione

Quando ricevi un 400, il messaggio nel body spesso indica esattamente cosa correggere.

## Quando contattare il supporto

Segnala al supporto Userbot se:

* Errori **500** persistenti su più richieste e sessioni diverse
* **401/403** nonostante credenziali corrette
* Webhook non consegnati nonostante endpoint HTTPS funzionante e HMAC corretto

Includi timestamp, `session` / `sessionId`, `eventId` (se applicabile) e status/body errore — **non** token o secret. Vedi [Supporto partner](/supporto-partner).