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

# 错误 - 状态码与错误码

> Apexium API 的错误响应体、全部错误码及其 HTTP 状态码，以及哪些错误可以重试。

所有错误共用同一个响应体：

```json theme={null}
{
  "code": "INVALID_STAKE",
  "message": "stake.amount must be a positive decimal with at most 2 decimals"
}
```

* `code` 保持稳定：请根据它进行分支处理。
* `message` 面向人类阅读，可能会变化。
* 部分错误带有 `details`，下文有说明。

可能会新增错误码。遇到未知错误码时，按其 HTTP 状态码对应的一般错误处理。

## 请求错误

| 错误码 | 状态码 | 含义 |
| - | - | - |
| `VALIDATION_FAILED` | 400 | 请求与 schema 不符。`details.errors` 列出若干 `{ field, message }` 对象。 |
| `MODE_REQUIRED` | 400 | `POST /v1/orders` 缺少 `mode`。它必须是 `"preview"` 或 `"place"`，没有默认值。 |
| `INVALID_STAKE` | 400 | `stake.amount` 不是最多两位小数的正数十进制数。 |
| `INVALID_PRICE` | 400 | `minPrice` 低于 1.001。 |
| `INVALID_EXPIRY` | 400 | `expiresAt` 已经过去，或比当前时间晚超过一小时。 |
| `CURRENCY_NOT_SUPPORTED` | 400 | `stake.currency` 不是账户币种。 |
| `BOOKMAKER_NOT_AVAILABLE_VIA_API` | 400 | 所请求的某个博彩公司对 API 关闭，即使它已在您的账户上启用。 |
| `INVALID_CURSOR` | 400 | 分页游标无效。请不带游标重新开始列表查询。 |
| `INVALID_WINDOW` | 400 | `from` 不早于 `to`，或时间窗口超过 366 天。 |
| `NOT_FOUND` | 404 | 您的账户下没有该资源，或路径不存在。 |

## 认证与访问

| 错误码 | 状态码 | 含义 |
| - | - | - |
| `INVALID_API_KEY` | 401 | 密钥缺失、无法识别、已吊销或已过期。 |
| `API_ACCESS_DENIED` | 403 | 账户不再具有 API 访问权限，或已被暂停。 |
| `ACCOUNT_NOT_ACTIVE` | 403 | 账户在当前状态下不能下单。 |
| `BOOKMAKER_NOT_AVAILABLE` | 403 | 所请求的某个博彩公司在您的账户上不可用。 |
| `BETTING_NOT_ALLOWED` | 403 | 您账户的规则不允许对该投注选项下注。 |
| `FORBIDDEN` | 403 | 该请求不被允许。 |

## 订单拒绝

以下是在向博彩公司发送任何内容之前进行的检查。任一检查失败时，不会记录任何内容：既没有订单，也没有注单。

检查通过后，订单即被记录。此后即使博彩公司拒绝，请求也不会失败。订单以 `201` 返回，每笔被拒绝的注单带有各自的 `declineReason`。所有注单都被拒绝时，订单状态为 `REJECTED`。

| 错误码 | 状态码 | 含义 |
| - | - | - |
| `INSUFFICIENT_FUNDS` | 400 | 可用余额不足以支付投注额。 |
| `MAX_STAKE_PER_FIXTURE_EXCEEDED` | 400 | 投注额超过了您在该赛事上的上限。`details` 包含 `maxStake`、`existingStake` 和 `remaining`。 |
| `PRICE_NOT_AVAILABLE` | 400 | 所请求的博彩公司没有有效价格。 |
| `PRICE_CHANGED` | 400 | 价格已跌破 `minPrice`。 |
| `NO_LIQUIDITY` | 400 | 在 `minPrice` 及以上没有流动性。 |
| `INSUFFICIENT_LIQUIDITY` | 400 | 流动性不足以覆盖全部投注额，且 `acceptPartialStake` 为 `false`。 |
| `CLIENT_ORDER_ID_REUSED` | 409 | 该 `clientOrderId` 属于另一笔条款不同的订单。参见[幂等性](https://docs.apexiumbet.com/zh/guides/idempotency.md)。 |
| `PREVIOUS_ATTEMPT_UNRESOLVED` | 409 | 使用该 `clientOrderId` 的先前尝试仍在处理中。请稍后重试同一请求。 |
| `ORDER_BUSY` | 409 | 该订单此刻正在被处理。请重试撤单。 |
| `CONFLICT` | 409 | 请求与当前状态冲突。 |

## 服务错误

| 错误码 | 状态码 | 含义 | 重试 |
| - | - | - | - |
| `RATE_LIMITED` | 429 | 请求过多。参见[限制](https://docs.apexiumbet.com/zh/api-reference/limits.md)。 | `retry-after` 秒后 |
| `INTERNAL_ERROR` | 500 | 意外错误。 | 是，需退避 |
| `UPSTREAM_UNAVAILABLE` | 502 | 博彩公司网关没有响应。订单可能已存在，也可能不存在。 | 用相同的 `clientOrderId` 重发同一请求，以读取该订单 |
| `FEED_UNAVAILABLE` | 502 | 行情数据服务没有响应。 | 是，需退避 |
| `BETTING_SUSPENDED` | 503 | 该投注选项或博彩公司已暂停投注。 | 稍后 |
| `EXPIRY_NOT_AVAILABLE` | 503 | 当前环境不支持带 `expiresAt` 的订单。 | 去掉 `expiresAt` |
| `BALANCE_UNAVAILABLE` | 409 | 余额暂时无法读取。 | 是，稍后 |
| `PUBLIC_API_DISABLED` | 503 | API 暂时被停用。 | 稍后 |
| `SERVICE_UNAVAILABLE` | 503 | 服务暂时不可用。 | 是，需退避 |
| `FEED_TIMEOUT` | 504 | 行情数据服务响应超时。 | 是，需退避 |

> [!TIP]
>
> 每个响应都带有 `x-request-id` 头。报告错误时请附上它。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.