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

# ABP 错误处理

> ABP API 错误码、验证错误、订单拒绝原因和可靠性模式。了解如何在集成中处理错误。

## 错误响应格式

ABP 返回两种格式的错误，取决于错误来源：

* **身份验证 / 速率限制中间件** 错误使用 `error` 键：

  ```json theme={null}
  { "error": "Invalid or inactive API key" }
  ```

* **应用 / 路由** 错误（验证、未找到等）使用 FastAPI 标准的 `detail` 键：

  ```json theme={null}
  { "detail": "No odds found for given parameters" }
  ```

请在客户端同时处理这两种格式。

请求体验证错误（`422`）包含带 `loc` 路径的字段级详情：

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "orders", 0, "orderStake"],
      "msg": "Input should be greater than 0",
      "type": "greater_than"
    }
  ]
}
```

## HTTP 状态码

| 状态码   | 描述                         |
| ----- | -------------------------- |
| `200` | 成功                         |
| `201` | 资源已创建                      |
| `204` | 资源已删除（无内容）                 |
| `400` | 错误请求 — 参数无效或缺失             |
| `401` | 未授权 — 无效或停用的API密钥          |
| `403` | 禁止 — 缺少API密钥头，或资源属于其他客户    |
| `404` | 未找到 — 资源不存在                |
| `409` | 冲突 — 请求中的每个订单都是重复的（见下文）    |
| `422` | 验证错误 — 请求体验证失败             |
| `429` | 速率限制 — 超出每秒请求数             |
| `500` | 内部服务器错误                    |
| `501` | 未实现 — 期货市场（`futureId`）尚不支持 |
| `503` | 服务不可用 — 数据库或依赖服务不可用        |

## 订单拒绝原因

通过 `POST /place-orders` 下单时，未通过业务验证的订单会在 `declinedOrders` 数组中返回（不作为HTTP错误）。每个被拒绝的订单包含 `declineReason`：

| 拒绝原因      | 描述                          |
| --------- | --------------------------- |
| 投注额超限     | `orderStake` 高于可用博彩公司限额     |
| 投注额低于最低要求 | `orderStake` 低于博彩公司或账户的最低限额 |
| 赔率无效      | `orderPrice` 不可用或市场已暂停      |
| 无活跃账户     | 此市场无可用的活跃博彩公司账户             |
| 货币转换失败    | 无法在订单货币和博彩公司货币之间转换          |
| 博彩公司不可用   | 指定的博彩公司没有此赛事/结果的赔率          |
| 赔率暂时不可用   | 无法及时获取赔率；请重试                |

<Note>
  重复的 `requestUuid` 不会作为拒绝原因返回。重复项会被静默跳过；如果请求中的**每个**订单都是重复的，则请求改为返回 `409`（见下文）。
</Note>

**被拒订单响应示例：**

```json theme={null}
{
  "status": "declined",
  "acceptedOrders": [],
  "declinedOrders": [
    {
      "requestUuid": "fb5f2dd9-c855-4ba9-8ef9-4c2278ca2f1d",
      "fixtureId": "id1000000861624412",
      "outcomeId": 161,
      "declineReason": "Order stake 15000.00 USD exceeds available limit 5000.00 USD",
      "bets": []
    }
  ]
}
```

## 常见错误

### 身份验证 (401 / 403)

```bash theme={null}
# 缺少头 → 403 {"detail": "Missing API key header: x-api-key"}
curl https://v2.55-tech.com/accounts

# 无效或停用的密钥 → 401 {"error": "Invalid or inactive API key"}
curl -H "x-api-key: wrong-key" https://v2.55-tech.com/accounts
```

### 禁止访问 (403)

当缺少API密钥头、密钥不允许访问所请求的端点/运动项目/博彩公司，或尝试访问属于其他客户的资源时返回。

```json theme={null}
{"detail": "Missing API key header: x-api-key"}
{"error": "Access denied to endpoint"}
{"detail": "Access denied: client not resolved"}
```

### 重复请求 (409)

仅当请求中的**每个**订单都是重复时返回 — 每个 `requestUuid` 在过去 **30 分钟** 内已被处理或正在处理中。如果只有部分订单是重复的，那些会被跳过，其余正常处理。

```json theme={null}
{
  "detail": {
    "error": "All orders are duplicates",
    "duplicateUuids": ["eb45b192-317b-42d5-9f65-af497b9fa8c1"],
    "inProgressUuids": []
  }
}
```

### 验证错误 (422)

请求体包含无效数据。检查 `loc` 字段以找到问题路径：

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "orders", 0, "fixtureId"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

### 速率限制 (429)

超出您客户的每**秒**请求数。默认限制：100/秒（每客户可配置）。

```json theme={null}
{
  "detail": "Rate limit exceeded",
  "limit": "100",
  "retry_after": 1
}
```

窗口每秒重置 — 重试前等待 `retry_after` 间隔。

## 可靠性模式

ABP 实施了多种可靠性机制，可能影响您的集成：

### 熔断器

每博彩公司熔断器防止级联故障。如果某个博彩公司出现问题，针对该博彩公司的订单可能被拒绝，直到熔断器恢复。

连续失败后打开，自动测试恢复，博彩公司成功响应后恢复正常运行。

### 紧急模式

在罕见情况下，系统可能在维护或上游问题期间临时暂停订单处理。`emergency` WebSocket频道广播状态变更。

### 订单过期

订单默认 `expiresAt` 为创建后5秒（最长上限为24小时）。如果在此窗口内未下注，订单状态变为 `EXPIRED`。可设置自定义 `expiresAt` 用于更长时效的订单。

## 后续步骤

<Columns cols={2}>
  <Card title="订单下注" icon="bullseye-arrow" href="/zh/abp-api/order-placement">
    了解成交、部分下注与拒绝原因。
  </Card>

  <Card title="WebSocket" icon="bolt" href="/zh/abp-api/websocket">
    实时跟踪订单与投注状态。
  </Card>
</Columns>