---
title: Errori & deprecati
description: Glossario dei codici di errore (RATE_LIMITED, IDEMPOTENCY_KEY_MISMATCH), tabella degli status HTTP con causa e azione, ed endpoint legacy /external/* deprecati.
---

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 `code` machine-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](/docs/api-rest/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`:

```json
{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests, please try again later."
  }
}
```

<Callout type="info">
  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](/docs/api-rest/idempotency-e-rate-limit).
</Callout>

## 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:

```json
{
  "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](/docs/api-rest/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 |

<Callout type="info">
  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.
</Callout>

## 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"
```

<Callout type="warn">
  **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.
</Callout>

<Callout type="info">
  Le rotte legacy `/external/*` usano anche un **envelope storico** diverso da
  quello delle rotte canonical. Per il dettaglio del formato vedi
  [Formato e convenzioni](/docs/api-rest/formato-e-convenzioni).
</Callout>

## Prossimo passo

<Cards>
  <Card href="/docs/api-rest/idempotency-e-rate-limit" title="Idempotency & rate limit" description="Gestione di RATE_LIMITED e IDEMPOTENCY_KEY_MISMATCH, header e backoff." />
  <Card href="/docs/api-rest/flussi" title="Flussi operativi" description="Apertura opportunità, invio preventivo e tracking firma contratto." />
</Cards>