> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oddspapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API错误代码 - HTTP状态码和错误处理

> OddsPapi API错误响应完整指南。HTTP状态码、错误格式、速率限制头和常见错误原因故障排除。

## 错误格式

大多数错误响应返回如下JSON对象：

```json theme={null}
{
  "error": 401,
  "message": "invalid apiKey",
  "code": "invalid_api_key"
}
```

| 字段        | 类型  | 描述        |
| --------- | --- | --------- |
| `error`   | 整数  | HTTP状态码   |
| `message` | 字符串 | 人类可读的描述   |
| `code`    | 字符串 | 机器可读的原因代码 |

***

## 速率限制头

所有受速率限制器保护的端点返回以下头：

| 头                       | 描述                   |
| ----------------------- | -------------------- |
| `X-RateLimit-Limit`     | 每个窗口允许的请求数（每个apiKey） |
| `X-RateLimit-Remaining` | 当前窗口剩余的请求数           |
| `X-RateLimit-Reset`     | 窗口重置的Unix时间戳         |

如果达到限制（`429`），您还会收到：

| 头             | 描述       |
| ------------- | -------- |
| `Retry-After` | 重试前等待的秒数 |

***

## 常见错误响应

### 400 — 错误请求

```json theme={null}
{
  "error": 400,
  "message": "Invalid filters.",
  "code": "invalid_filters"
}
```

用于语法有效但参数无效的请求。

***

### 401 — 未授权

**缺少或无效的`apiKey`。**

```json theme={null}
{
  "error": 401,
  "message": "missing apiKey",
  "code": "missing_api_key"
}
```

```json theme={null}
{
  "error": 401,
  "message": "invalid apiKey",
  "code": "invalid_api_key"
}
```

***

### 403 — 禁止

**有效的API密钥，但无权访问此频道或功能。**

```json theme={null}
{
  "error": 403,
  "message": "Access denied: apiKey is not allowed to access this endpoint.",
  "code": "channel_not_allowed"
}
```

***

### 422 — 验证错误

通常由FastAPI的内部验证返回。

```json theme={null}
{
  "error": 422,
  "message": "Validation error",
  "code": "validation_error",
  "details": [
    {
      "loc": ["query", "fixtureId"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

***

### 429 — 超出速率限制

当请求量超过每个apiKey的限制时触发。

```json theme={null}
{
  "error": 429,
  "message": "rate limit exceeded",
  "code": "rate_limited",
  "limit": 30,
  "windowSec": 1,
  "retryAfterSec": 1,
  "endpoint": "/fixtures/odds",
  "method": "GET"
}
```

头：

* `Retry-After: 1`
* `X-RateLimit-Limit: 30`
* `X-RateLimit-Remaining: 0`
* `X-RateLimit-Reset: 1700000000`

***

### 503 — 服务不可用

如果内部系统（如速率限制器）不可用：

```json theme={null}
{
  "error": 503,
  "message": "rate limiter unavailable",
  "code": "rate_limiter_error"
}
```

## 说明

* `code`是稳定的，适合程序化处理。
* `message`可能会更改（但旨在帮助开发人员）。
* 大多数端点在速率限制时返回`429`——请检查您的头。
* FastAPI验证错误始终作为`422`返回。

***