# 错误

> TMDB 风格调用返回 success 为 false 的错误体，含 status_code 和 status_message。OMDb 风格返回 Response False 和 Error。amodb 用 8 个状态码，只重试 429、500、504。

## TMDB 风格的错误响应体

`https://api.amodb.dev/3` 返回的每个错误，都有与 TMDB 相同的 JSON 结构：

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

## 错误码

| HTTP | status_code | status_message                                                               | 应对方式                      |
| ---- | ----------- | ---------------------------------------------------------------------------- | ------------------------- |
| 401  | 7           | Invalid API key: You must be granted a valid key.                            | 检查密钥及其发送方式。               |
| 401  | 10          | Suspended API key: Access to your account has been suspended, contact amodb. | 请写信至 <support@amodb.dev>。 |
| 402  | 36          | Your plan has expired. Renew at <https://amodb.dev/pricing>                  | 支付新的周期。                   |
| 404  | 34          | The resource you requested could not be found.                               | 检查 ID 或路径。                |
| 405  | 37          | This method is not offered by amodb.                                         | 使用读取接口。                   |
| 429  | 25          | Your request count (N) is over the allowed limit of (L).                     | 等待 `Retry-After` 秒。       |
| 500  | 11          | Internal error: Something went wrong, contact amodb.                         | 几秒后重试。                    |
| 504  | 24          | Your request to the backend server timed out. Try again.                     | 几秒后重试。                    |

## OMDb 风格的错误响应体

兼容 OMDb 的接口保持 OMDb 的结构和措辞：

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

带 `r=xml` 的 OMDb 调用返回 HTTP 400。请使用 `r=json`，或者省略 `r`。

## 在代码中处理错误

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

## 不算错误的回退

- 未知的 `language` 标签不会失败，amodb 会返回英语。
- 没有数据的字段与 TMDB 一样，是 `null` 或空数组。

## 常见问题

### 我的客户端应该重试哪些错误？

429 在 Retry-After 秒之后重试，500 或 504 以几秒的退避重试。不要重试 401、402、404 或 405：同样的调用会再次失败。

### 为什么 TMDB 的某个接口返回 405？

amodb 不提供 TMDB 账户、会话、评分和列表的写入方法。它们返回 405 和 status_code 37。读取接口都可用。

## 相关页面

- [速率限制](https://amodb.dev/zh/rate-limits/): amodb 按滑动 60 秒窗口内每分钟请求数限制每个密钥：按套餐为 20、40 或 120。读取速率限制响应头，并用 Retry-After 处理 429。
- [认证](https://amodb.dev/zh/authentication/): 如何发送 amodb 密钥：查询中的 api_key、Bearer 请求头，或 OMDb 的 apikey。含密钥格式、保管和 401 错误。
- [快速开始](https://amodb.dev/zh/quickstart/): 发出第一次 amodb 调用：获取密钥，用 curl、JavaScript、Python、PHP 或 Go 请求电影详情，再加载海报。

更新于: 2026-10-18. Source: https://amodb.dev/zh/errors/