# Errori

> Le chiamate in stile TMDB restituiscono gli errori nel corpo TMDB: success false, uno status_code numerico e uno status_message. Le chiamate in stile OMDb restituiscono Response False con una stringa Error. amodb usa 8 codici TMDB, da 7 per una chiave non valida a 25 per il limite e 36 per un piano scaduto. Riprova solo 429, 500 e 504.

## Corpo dell'errore in stile TMDB

Ogni errore di `https://api.amodb.dev/3` ha la stessa forma JSON di TMDB:

```json
{
  "success": false,
  "status_code": 34,
  "status_message": "The resource you requested could not be found."
}
```

## Codici di errore

| HTTP | status_code | status_message                                                               | Cosa fare                                    |
| ---- | ----------- | ---------------------------------------------------------------------------- | -------------------------------------------- |
| 401  | 7           | Invalid API key: You must be granted a valid key.                            | Controlla la chiave e come la invii.         |
| 401  | 10          | Suspended API key: Access to your account has been suspended, contact amodb. | Scrivi a <support@amodb.dev>.                |
| 402  | 36          | Your plan has expired. Renew at <https://amodb.dev/pricing>                  | Paga un nuovo periodo.                       |
| 404  | 34          | The resource you requested could not be found.                               | Controlla l'ID o il percorso.                |
| 405  | 37          | This method is not offered by amodb.                                         | Usa un endpoint di lettura.                  |
| 429  | 25          | Your request count (N) is over the allowed limit of (L).                     | Attendi i secondi indicati da `Retry-After`. |
| 500  | 11          | Internal error: Something went wrong, contact amodb.                         | Riprova dopo qualche secondo.                |
| 504  | 24          | Your request to the backend server timed out. Try again.                     | Riprova dopo qualche secondo.                |

## Corpo dell'errore in stile OMDb

L'endpoint compatibile con OMDb mantiene la forma e le parole di OMDb:

```json
{
  "Response": "False",
  "Error": "Movie not found!"
}
```

Una chiamata OMDb con `r=xml` restituisce HTTP 400. Usa `r=json` oppure ometti `r`.

## Gestire gli errori nel codice

```js
const res = await fetch("https://api.amodb.dev/3/movie/550", {
  headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` },
});
if (!res.ok) {
  const err = await res.json();
  if (res.status === 429) {
    // wait Retry-After seconds, then retry
  }
  throw new Error(`amodb ${res.status} code ${err.status_code}: ${err.status_message}`);
}
```

```python
res = requests.get(url, headers=headers, timeout=10)
if not res.ok:
    err = res.json()
    raise RuntimeError(f"amodb {res.status_code} code {err['status_code']}: {err['status_message']}")
```

## Ripieghi che non sono errori

- Un tag `language` sconosciuto non fa fallire la chiamata. amodb serve l'inglese.
- Un campo senza dati è `null` o un array vuoto, come in TMDB.

## Domande e risposte

### Quali errori deve riprovare il mio client?

Riprova 429 dopo i secondi indicati da Retry-After, e 500 o 504 con un backoff di alcuni secondi. Non riprovare 401, 402, 404 o 405: la stessa chiamata fallisce di nuovo.

### Perché ricevo 405 per un endpoint TMDB?

amodb non offre i metodi di scrittura TMDB per account, sessioni, valutazioni e liste. Restituiscono 405 con status_code 37. Gli endpoint di lettura funzionano tutti.

## Pagine correlate

- [Limiti di richieste](https://amodb.dev/it/rate-limits/): amodb limita ogni chiave per richieste al minuto in una finestra scorrevole di 60 secondi: 20, 40 o 120 in base al piano. Leggi gli header, gestisci il 429.
- [Autenticazione](https://amodb.dev/it/authentication/): Come inviare la chiave amodb: api_key nella query, un header Authorization Bearer o apikey per le chiamate OMDb. Formato, conservazione, rotazione, errori 401.
- [Avvio rapido](https://amodb.dev/it/quickstart/): Fai la prima chiamata ad amodb: ottieni una chiave, richiedi i dettagli di un film in curl, JavaScript, Python, PHP o Go, carica la locandina. Meno di 2 minuti.

Aggiornato: 2026-10-18. Source: https://amodb.dev/it/errors/