---
url: https://limapi.com/docs/guide/errors.md
---
# 错误码参考

当请求发生错误时，API 返回统一的错误体：

```json
{
  "error": {
    "code": "402",
    "type": "insufficient_balance",
    "message": "余额不足，请充值",
    "request_id": "3f2a1c9d8e7b4a6f"
  }
}
```

::: warning 注意 code 与 type 的含义

* `error.code` 是 **HTTP 状态码的字符串形式**（如 `"402"`、`"429"`），不是语义名。
* `error.type` 才是**语义错误名**（如 `insufficient_balance`）。
* `request_id` 与响应头 `X-RealApi-RequestId` 一致，**报障时请提供它**，可据此定位到具体那一笔调用。
* 上游透传的错误，`code` 可能是上游返回的原始状态码，`type` 为 `provider_api_error`。
* Anthropic 端点（`/api/anthropic/...`）返回 Anthropic 自己的错误体格式，语义相同。
  :::

## 平台侧错误

| HTTP 状态码 | `error.type` | 说明 |
|------|------|------|
| 400 | `invalid_params` | 请求参数无效；模型不支持图片/视频输入；上下文超长 |
| 402 | `insufficient_balance` | 账户余额不足，充值后重试 |
| 402 | `key_credit_exhausted` | 该 API Key 的额度上限已用尽（账户余额可能仍充足） |
| 403 | `access_denied` | 未提供 API Key，或 Key 无效 / 已暂停 / 已删除 |
| 404 | `invalid_model` | 模型 ID 不存在 |
| 404 | `model_not_available` | 模型存在但当前不可用 |
| 404 | `model_not_supported` | 该模型不支持你调用的这个 API（如用 `/responses` 调只支持 `/chat/completions` 的模型） |
| 413 | `request_body_too_large` | 请求体超过 32 MB（多模态请压缩图片或改用图片 URL） |
| 429 | `rate_limit` | 超过该 Key 的 RPM 上限，**或**超大请求（> 8 MB）并发额度已满；响应带 `Retry-After: 5`，可重试 |
| 500 | `internal_server_error` | 平台内部错误 |
| 502 | `no_provider_available` | 该模型当前没有可用渠道（全部渠道不可用或不满足约束） |

## 上游相关错误

| HTTP 状态码 | `error.type` | 说明 |
|------|------|------|
| 422 | `provider_unprocessable_entity_error` | 上游拒绝了请求内容 |
| 429 | `rate_limited` | 上游模型服务方限流 |
| 500 | `provider_api_error` | 上游 API 返回错误（`code` 可能是上游原始状态码） |
| 500 | `provider_error` | 上游服务错误 |
| 520 | `provider_internal_server_error` | 与上游通信故障 |
| 524 | `provider_internal_server_error` | 上游超时 |

## 排查建议

| 错误 | 排查方向 |
|------|------|
| `access_denied` | 检查 Key 是否复制完整、是否已在 Portal 暂停或删除 |
| `insufficient_balance` | 登录 Portal 查看余额并充值；建议开启低余额提醒，见[按量付费](/platform/pay-as-you-go#低余额提醒) |
| `key_credit_exhausted` | 该 Key 设了额度上限且已用尽，联系平台支持调整或换用其他 Key |
| `rate_limit` | 降低请求频率；若是大请求（> 8 MB）并发导致，按 `Retry-After` 退避重试，或压缩请求体 |
| `invalid_model` / `model_not_available` | 用 `GET /api/v1/models` 确认模型 ID 与可用状态 |
| `model_not_supported` | 换用该模型支持的协议端点 |
| `request_body_too_large` | 压缩图片（转 JPEG / 降分辨率，单图建议 5 MB 内）或改用图片 URL，不要整段 base64 塞进请求 |
| `no_provider_available` | 该模型暂无可用渠道，稍后重试或换用同类模型 |
| `provider_*` | 上游模型服务方的问题，可稍后重试；持续出现请带 `request_id` 联系平台支持 |

## 健康检查

```
GET /health
```

无需认证，用于检查 Gateway 服务状态。

```json
{
  "status": "UP"
}
```