Errori & deprecati
Glossario dei codici di errore (RATE_LIMITED, IDEMPOTENCY_KEY_MISMATCH), tabella degli status HTTP con causa e azione, ed endpoint legacy /external/* deprecati.
Versione Markdown di questa pagina
Scarica o copia il contenuto di questa pagina in formato .md — utile per fornirlo a un agente AI che integra questa specifica feature.
Questa pagina raccoglie come l'API REST partner segnala gli errori e quali endpoint sono deprecati. Distingue i due casi:
- gli errori trasversali con un
codemachine-readable (rate limit e mismatch di idempotency); - gli errori delle rotte di risorsa, in forma raw
{ "error": "..." }con uno status HTTP significativo.
Per il formato delle risposte di successo e degli errori vedi Formato e convenzioni.
Glossario dei codici trasversali
Due controlli trasversali espongono un code dedicato per la gestione
automatica. A differenza degli errori di risorsa, usano un envelope con
code/message:
| Code | HTTP | Significato | Azione |
|---|---|---|---|
RATE_LIMITED | 429 | Superato il limite di richieste per API Key | Rispetta l'header Retry-After, poi ritenta con backoff esponenziale |
IDEMPOTENCY_KEY_MISMATCH | 422 | Stessa Idempotency-Key riusata con un body diverso | Usa una Idempotency-Key (UUID v4) fresca per la nuova operazione |
Esempio di risposta 429:
{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests, please try again later."
}
}Questo envelope con code/message è la forma dei controlli trasversali
(rate limiter e idempotency) e differisce dal formato raw
{ "error": "..." } delle rotte di risorsa. Distingui i due casi sul code
quando gestisci gli errori a livello di codice. Vedi
Idempotency & rate limit.
Errori delle rotte di risorsa
Sulle rotte canonical, gli altri errori tornano in forma raw, con lo status HTTP come fonte di verità per la gestione automatica:
{
"error": "Lead not found"
}| HTTP | Tipica causa | Azione suggerita |
|---|---|---|
400 | Body invalido / campi obbligatori mancanti | Correggi il body e ritenta |
401 | Header X-API-Key mancante o invalido | Verifica la chiave (vedi Autenticazione) |
403 | Risorsa di un altro account | Non ritentabile — la risorsa non è accessibile |
404 | Risorsa inesistente | Verifica l'id |
409 | Conflict (es. unique constraint, vincolo FK) | Ritenta solo dopo aver risolto il conflitto |
500 | Errore interno | Ritenta con backoff esponenziale |
Lo status code è sempre la fonte di verità: basa la logica di retry su di
esso. I 4xx (eccetto 429) non sono ritentabili senza correggere la
richiesta; i 5xx e i 429 sono ritentabili con backoff.
Endpoint deprecati
Le rotte legacy /external/* sono deprecate e verranno rimosse. Hanno un
successore canonical funzionalmente equivalente; le risposte includono gli
header RFC 9745 (Deprecation, Sunset, Link).
| Path legacy | Successore | Sunset |
|---|---|---|
POST /external/leads | POST /leads | 2026-12-31 |
POST /external/companies | POST /companies | 2026-12-31 |
POST /external/deals | POST /deals | 2026-12-31 |
GET/POST /external/activities | GET/POST /activities | 2026-12-31 |
Le risposte di queste rotte segnalano la deprecazione con header standard:
HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://api.audin.ai/leads>; rel="successor-version"Azione richiesta: migra alle rotte canonical prima del Sunset
(2026-12-31). Le implementazioni sono funzionalmente equivalenti — basta
cambiare il path (rimuovere il prefisso /external). Non costruire nuove
integrazioni sulle rotte legacy.
Le rotte legacy /external/* usano anche un envelope storico diverso da
quello delle rotte canonical. Per il dettaglio del formato vedi
Formato e convenzioni.