# Erros

> As chamadas no estilo TMDB retornam erros no corpo do TMDB: success false, um status_code numérico e um status_message. As chamadas no estilo OMDb retornam Response False com uma string Error. O amodb usa 8 códigos do TMDB, de 7 para chave inválida a 25 para o limite e 36 para plano expirado. Repita apenas 429, 500 e 504.

## Corpo de erro no estilo TMDB

Todo erro de `https://api.amodb.dev/3` tem o mesmo formato JSON do TMDB:

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

## Códigos de erro

| HTTP | status_code | status_message                                                               | O que fazer                            |
| ---- | ----------- | ---------------------------------------------------------------------------- | -------------------------------------- |
| 401  | 7           | Invalid API key: You must be granted a valid key.                            | Verifique a chave e como você a envia. |
| 401  | 10          | Suspended API key: Access to your account has been suspended, contact amodb. | Escreva para <support@amodb.dev>.      |
| 402  | 36          | Your plan has expired. Renew at <https://amodb.dev/pricing>                  | Pague um novo período.                 |
| 404  | 34          | The resource you requested could not be found.                               | Verifique o id ou o caminho.           |
| 405  | 37          | This method is not offered by amodb.                                         | Use um endpoint de leitura.            |
| 429  | 25          | Your request count (N) is over the allowed limit of (L).                     | Aguarde `Retry-After` segundos.        |
| 500  | 11          | Internal error: Something went wrong, contact amodb.                         | Tente de novo após alguns segundos.    |
| 504  | 24          | Your request to the backend server timed out. Try again.                     | Tente de novo após alguns segundos.    |

## Corpo de erro no estilo OMDb

O endpoint compatível com OMDb mantém o formato e o texto do OMDb:

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

Uma chamada OMDb com `r=xml` retorna HTTP 400. Use `r=json` ou omita `r`.

## Trate os erros no código

```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 que não são erros

- Uma tag `language` desconhecida não falha. O amodb serve o inglês para ela.
- Um campo sem dados é `null` ou um array vazio, como no TMDB.

## Perguntas e respostas

### Quais erros meu cliente deve repetir?

Repita o 429 após Retry-After segundos, e o 500 ou 504 com um backoff de alguns segundos. Não repita 401, 402, 404 nem 405: a mesma chamada falha de novo.

### Por que recebo 405 em um endpoint do TMDB?

O amodb não oferece os métodos de escrita do TMDB para conta, sessão, avaliação e lista. Eles retornam 405 com status_code 37. Todos os endpoints de leitura funcionam.

## Páginas relacionadas

- [Limites de requisições](https://amodb.dev/pt/rate-limits/): O amodb limita cada chave por requisições por minuto em uma janela de 60 segundos: 20, 40 ou 120 por plano. Leia os cabeçalhos e trate o 429 com Retry-After.
- [Autenticação](https://amodb.dev/pt/authentication/): Como enviar sua chave do amodb: api_key na consulta, um cabeçalho Authorization Bearer ou apikey nas chamadas OMDb. Formato, armazenamento, rotação e erros 401.
- [Início rápido](https://amodb.dev/pt/quickstart/): Faça sua primeira chamada ao amodb: obtenha uma chave, peça um filme em curl, JavaScript, Python, PHP ou Go e carregue o pôster. Menos de 2 minutos.

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