Errori

Gli errori condividono un unico envelope (vedi la panoramica). Basa la logica su code, registra meta.request_id nei log e considera message come testo in inglese destinato alle persone.

Errori del client

Codice	Stato	Significato e cosa fare
validation_failed	400	Un campo non ha superato la validazione. field lo indica; details spiega il motivo. Correggi il campo.
bad_request	400	Non è stato possibile leggere la richiesta: JSON malformato, flusso Content-Encoding corrotto, corpo interrotto. Non c’è un campo da correggere; controlla il trasporto.
validation_error	400	X-Account-Id è stato inviato a un endpoint che lo vieta (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Il cursore di paginazione ha più di 24 ore. Ricomincia l’elenco.
unauthenticated	401	Token mancante o non valido. Rinnova la sessione o controlla la chiave.
invalid_signature	401	La firma di un webhook non è stata verificata. Vedi Webhook.
forbidden	403	Il token è valido ma non ha il permesso.
account_context_mismatch	403	X-Account-Id non corrisponde all’account del token. L’azienda corrente secondo il client non è più allineata; rileggila dalla sessione.
not_found	404	La risorsa non esiste oppure appartiene a un altro account o sito. L’API non distingue mai i due casi.
conflict	409	Conflitto di stato: lock ottimistico, vincolo di unicità o azione non consentita nello stato attuale (per esempio scrivere in una conversazione unita).
idempotency_key_conflict	409	La Idempotency-Key è stata riutilizzata con un corpo diverso.
payload_too_large	413	Il corpo supera il limite per questa famiglia di endpoint.
unsupported_media_type	415	Content-Type errato.
unprocessable	422	JSON valido, ma rifiutato da una regola di business (per esempio uno slot di prenotazione fuori dagli orari di lavoro).
storage_quota_exceeded	422	L’account ha raggiunto il limite di spazio del suo piano. details riporta used_bytes, quota_bytes e requested_bytes; libera spazio o passa a un piano superiore.
rate_limited	429	Rallenta. Rispetta Retry-After e details.retry_after_seconds.

Errori del server

Codice	Stato	Significato e cosa fare
internal_error	500	Errore imprevisto. Riprova una volta, poi contatta il supporto indicando il request_id.
upstream_unavailable	502	Il gateway non è riuscito a raggiungere il servizio. Un nuovo tentativo a breve di solito va a buon fine.
service_unavailable	503	Manutenzione programmata o circuit breaker aperto. Riprova dopo il tempo indicato dall’intestazione Retry-After.
ai_vendor_out_of_funds	503	Il tuo provider AI ha rifiutato la chiamata per motivi di fatturazione (un 402 o un 429 di quota dal fornitore). Ricarica l’account presso il fornitore; ripetere la chiamata non serve.
upstream_timeout	504	Il servizio non ha risposto in tempo. Riprova quando è presente retry_after.

Nuovi tentativi

Ripeti le richieste in caso di 429, 502, 503, 504 e di errori di rete con backoff esponenziale, e invia la stessa Idempotency-Key nel nuovo tentativo, così una scrittura non viene mai applicata due volte. Non ripetere i 4xx diversi da 429.