# Errors

> TMDB style calls return errors in the TMDB body: success false, a numeric status_code and a status_message. OMDb style calls return Response False with an Error string. amodb uses 8 TMDB codes, from 7 for an invalid key to 25 for the rate limit and 36 for an expired plan. Retry only 429, 500 and 504.

## TMDB style error body

Every error from `https://api.amodb.dev/3` has the same JSON shape as TMDB:

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

## Error codes

| HTTP | status_code | status_message                                                               | What to do                         |
| ---- | ----------- | ---------------------------------------------------------------------------- | ---------------------------------- |
| 401  | 7           | Invalid API key: You must be granted a valid key.                            | Check the key and how you send it. |
| 401  | 10          | Suspended API key: Access to your account has been suspended, contact amodb. | Write to <support@amodb.dev>.      |
| 402  | 36          | Your plan has expired. Renew at <https://amodb.dev/pricing>                  | Pay for a new period.              |
| 404  | 34          | The resource you requested could not be found.                               | Check the id or path.              |
| 405  | 37          | This method is not offered by amodb.                                         | Use a read endpoint.               |
| 429  | 25          | Your request count (N) is over the allowed limit of (L).                     | Wait for `Retry-After` seconds.    |
| 500  | 11          | Internal error: Something went wrong, contact amodb.                         | Retry after a few seconds.         |
| 504  | 24          | Your request to the backend server timed out. Try again.                     | Retry after a few seconds.         |

## OMDb style error body

The OMDb compatible endpoint keeps the OMDb shape and wording:

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

An OMDb call with `r=xml` returns HTTP 400. Use `r=json` or leave `r` out.

## Handle errors in code

```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']}")
```

## Fallbacks that are not errors

- An unknown `language` tag does not fail. amodb serves English for it.
- A field with no data is `null` or an empty array, as in TMDB.

## Questions and answers

### Which errors should my client retry?

Retry 429 after Retry-After seconds, and 500 or 504 with a backoff of a few seconds. Do not retry 401, 402, 404 or 405: the same call fails again.

### Why do I get 405 for a TMDB endpoint?

amodb does not offer TMDB account, session, rating and list write methods. They return 405 with status_code 37. Read endpoints all work.

## Related pages

- [Rate limits](https://amodb.dev/rate-limits/): amodb limits each key by requests per minute in a sliding 60 second window: 20, 40 or 120 by plan. Read the rate limit headers and handle 429 with Retry-After.
- [Authentication](https://amodb.dev/authentication/): How to send your amodb key: api_key in the query, an Authorization Bearer header, or apikey for OMDb calls. Key format, storage, rotation and the 401 errors.
- [Quickstart](https://amodb.dev/quickstart/): Make your first amodb call: get a key, request movie details in curl, JavaScript, Python, PHP or Go, then load the poster from img.amodb.dev. Under 2 minutes.

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