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

# Errors

> DimiLinks API 的错误响应格式和常见 HTTP 状态。

DimiLinks 的错误响应格式与上游协议保持一致：

* 调用 `https://dimilinks.com/v1/*`（OpenAI 兼容）的接口，错误使用 OpenAI 风格 `error` 包装。
* 调用 `https://api-direct.dimilinks.com/v1/messages`（Anthropic 原生）的接口，错误使用 Anthropic 原生格式 `{"type":"error","error":{...}}`。

OpenAI 风格（来自 `dimilinks.com/v1`）：

```json theme={null}
{
  "error": {
    "message": "prompt 不能为空",
    "type": "invalid_request_error",
    "code": "invalid_request_error"
  }
}
```

Anthropic 风格（来自 `api-direct.dimilinks.com`）：

```json theme={null}
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages 不能为空"
  }
}
```

## 常见错误

|          HTTP | code                                                | 含义                                       | 调用方建议                                                                                   |
| ------------: | --------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------- |
|         `400` | `invalid_request_error` / `invalid_reference_image` | 参数错误、prompt 为空、参考图异常                     | 提示用户修改参数                                                                                |
|         `401` | `missing_api_key` / `invalid_api_key`               | 密钥缺失或错误                                  | 检查密钥配置                                                                                  |
|         `402` | `insufficient_balance`                              | 余额不足                                     | 提示充值或联系管理员                                                                              |
|         `403` | `model_not_allowed`                                 | 当前密钥没有该模型权限，或可用分组与模型 `enable_groups` 无交集 | 检查模型白名单、参考 [Model groups & pricing](/api-reference/groups-and-pricing) 调整 `group` 或更换密钥 |
|         `404` | `not_found`                                         | 任务不存在或不属于当前用户                            | 停止轮询                                                                                    |
|         `429` | `rate_limit_rpm` / `rate_limit_tpm`                 | 限流                                       | 退避后重试，降低并发                                                                              |
|         `500` | `internal_error` / `billing_error`                  | 服务内部异常                                   | 记录日志并稍后重试                                                                               |
| `502` / `503` | `upstream_error` / `service_unavailable`            | 上游渠道暂时不可用                                | 可允许用户重试                                                                                 |

## 处理建议

* `400` 把 `error.message` 直接展示给用户，便于调整输入。
* `401` / `403` 提示检查密钥或模型权限，不要静默重试。
* `429` 建议指数退避，并降低并发；不要立即高频重试。
* `5xx` / `502` / `503` 可允许用户重试，但要记录日志便于排查上游。
* 任务接口返回 `404` 时立即停止轮询，避免浪费请求。
* 同一段业务代码如果同时调用两套域名，建议在 HTTP 客户端里统一抽象「读 `error.message` 或 `error.error.message`」，避免每个调用方各写一遍兼容逻辑。