Codici di errore | Userbot | Documentazione per sviluppatori

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 — 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
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
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 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.