# 错误 (/docs/api/errors)



出错时，HTTP 状态码告诉你错误属于哪一类；错误体按该前缀的格式给出具体原因；每个错误响应还带四个 `x-praxis-problem-*` 头和一个 `x-praxis-recovery-action`（限流错误再多带一个 `x-praxis-problem-scope`，见[限流](/docs/api/rate-limits)），不论错误体长什么样，重试逻辑只看头就够。

## 状态码 [#状态码]

| 状态码   | 含义             | 你该做什么                          |
| ----- | -------------- | ------------------------------ |
| `400` | 请求字段或格式不合法     | 修正参数，不要原样重试                    |
| `401` | 缺少或无效的凭证       | 检查 API Key                     |
| `402` | 余额或付费额度不足      | 补充余额或联系账户管理员                   |
| `403` | 无权访问该资源或操作     | 核对 Key 权限与资源归属；必要时联系支持         |
| `404` | 资源、模型或路径不存在    | 检查 ID、模型名和路径                   |
| `408` | 请求超时           | 检查网络后重试；写操作先确认是否已完成            |
| `409` | 资源状态或并发修改冲突    | 重新读取状态，再调整请求                   |
| `413` | 请求体或文件超过大小限制   | 减小内容或改用端点支持的 URL 输入            |
| `422` | 请求内容无法处理       | 根据错误详情修正参数或输入                  |
| `429` | 请求速率、并发或模型额度超限 | 按 retry-after 等待；并发超限时等待在途请求结束 |
| `500` | 平台内部错误         | 稍后重试；持续出现请附 X-Request-Id 联系支持  |
| `501` | 功能尚未支持         | 换用已支持的端点，不要重试                  |
| `502` | 上游调用失败或返回无效响应  | 退避重试，持续失败时换模型或联系支持             |
| `503` | 服务或可用线路暂不可用    | 退避重试，或选择其它模型                   |
| `504` | 上游响应超时         | 退避重试；写操作先确认结果，避免重复创建           |

## 错误码 [#错误码]

以下是常见的机器可读错误码，不是所有端点的封闭枚举。兼容接口的错误体可能使用协议自己的 code/type；跨协议判断可读取 `x-praxis-problem-code`，其值可能与错误体 code 不同。大小写按返回值区分。

| code                                          | 什么时候出现、该怎么办                                                                                                                                                                    |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AUTHENTICATION_ERROR`                        | Key 缺失或无效；检查并更换凭证。                                                                                                                                                             |
| `VALIDATION_ERROR`                            | 参数不符合格式、类型或范围要求；按详情改参数。                                                                                                                                                        |
| `INPUT_NOT_REPRESENTABLE`                     | 所选模型或协议无法表达输入选项；删除该选项或换模型。                                                                                                                                                     |
| `NOT_FOUND`                                   | 资源不存在或对当前账户不可见；核对 ID 与账户。                                                                                                                                                      |
| `MODEL_NOT_FOUND`                             | 模型不存在或不可见；从模型列表选取可用名称。                                                                                                                                                         |
| `MODEL_PROTOCOL_NOT_OFFERED`                  | 模型不提供所请求的协议；换用其支持的端点或模型。                                                                                                                                                       |
| `MODEL_PROTOCOL_LINE_UNAVAILABLE`             | 支持该协议的合格线路暂不可用；退避重试或换模型。                                                                                                                                                       |
| `GENERATION_NOT_FOUND`                        | 生成记录不存在或不属于当前账户；核对响应头中的生成 ID 与 Key。                                                                                                                                            |
| `RATE_LIMITED`                                | 超过速率或并发限额；按 retry-after 等待并降低速率或并发。                                                                                                                                            |
| `UPSTREAM_ERROR`                              | 上游调用失败或响应不合法；按 retryable 退避重试，持续失败时换模型或联系支持。                                                                                                                                   |
| `PROVIDER_SELECTION_NOT_ALLOWED`              | 指定供应商 order/only 时没有携带 BYOK；移除供应商选择或提供自己的上游 Key。                                                                                                                               |
| `not_implemented`                             | 该端点或能力未实现；换用已支持的能力，不要原样重试。                                                                                                                                                     |
| `model_protocol_not_offered`                  | HTTP 404；模型未声明所请求的协议。查询 `GET /model/v1/models` 的 `supported_apis`，改用相应入口，例如声明 Google 协议的模型使用 `/google/v1beta/models/{model}:generateContent`；不要只换前缀而保留另一协议的请求体。                |
| `provider_unavailable`                        | HTTP 502；本次请求的可用线路全部失败。退避重试，持续失败时换模型，并附 `X-Request-Id` 联系支持。                                                                                                                   |
| `thinking_disable_unsupported`                | HTTP 400；模型不能关闭思考，例如对 `glm-5.3` 设置 `reasoning_effort="none"`。移除关闭设置或选择支持的思考等级；需要关闭思考时换模型。                                                                                      |
| `insufficient_quota` / `INSUFFICIENT_BALANCE` | HTTP 402；余额不足，错误体或响应头的代码因入口而异。充值或联系账户管理员后再重试，不要立即循环重试。                                                                                                                         |
| `validation_error`（`response_format`）         | HTTP 400；例如 `Model "deepseek-flash" does not support json_schema on this API.`。换用在该入口支持 `json_schema` 的模型；若只需要合法 JSON，可改用 `json_object`，但它不保证 schema 约束。                       |
| `validation_error`（参数被点名）                     | HTTP 400；设置 `provider.require_parameters=true` 时，所选模型仍可能无法支持请求参数，例如 `param: "logprobs"`、`does not support the requested logprobs value`。按 `param` 和消息调整参数或换模型；不要只关闭检查后假定参数已生效。 |

## 错误体 [#错误体]

错误体的格式跟着地址第一段走，和成功响应一致——你的 SDK 不需要为错误特殊处理。

**厂商前缀**（`/openai` `/anthropic` `/google` `/e2b` `/tavily`）：和该前缀对应的官方 API 错误体一模一样。

```json
// /openai
{ "error": { "code": 401, "message": "Invalid API key." } }
```

```json
// /anthropic
{ "type": "error", "error": { "type": "authentication_error", "message": "Invalid API key." } }
```

**Praxis 前缀**（`/agent` `/model` `/sandbox` `/search` `/meta`）：标准的 Problem Details（RFC 9457），`Content-Type: application/problem+json`。

```json
{
  "type": "https://deepraxis.ai/problems/authentication_error",
  "title": "authentication_error",
  "status": 401,
  "detail": "Invalid API key.",
  "instance": "problem_eqfnxu",
  "code": "AUTHENTICATION_ERROR",
  "retryable": false
}
```

| 字段                 | 含义                 |
| ------------------ | ------------------ |
| `type`             | 错误类型的 URL，稳定，可用来分支 |
| `title` / `detail` | 给人读的摘要与具体原因        |
| `status`           | 同 HTTP 状态码         |
| `instance`         | 本次错误的 ID，联系支持时附上   |
| `code`             | 机器可读的错误码           |
| `retryable`        | 原样重试是否可能成功         |

## 错误响应头（五个通用头 + 一个限流头） [#错误响应头五个通用头--一个限流头]

五个通用头与错误体格式无关；第六个 scope 头仅适用于限流错误：

| 头                            | 含义                                                                    | 例子                       |
| ---------------------------- | --------------------------------------------------------------------- | ------------------------ |
| `x-praxis-problem-code`      | 跨协议分类码；可能与错误体的 `code` 不同                                              | `AUTHENTICATION_ERROR`   |
| `x-praxis-problem-kind`      | 错误大类——出了什么事                                                           | `authentication_failure` |
| `x-praxis-problem-origin`    | 错误归谁——谁能解决它：`user`（你的请求或凭证）、`platform`（我们）、`upstream_provider`（上游厂商）等 | `unknown`                |
| `x-praxis-problem-retryable` | 原样重试是否可能成功                                                            | `false`                  |
| `x-praxis-problem-scope`     | 仅限流错误：触发的保护层——`platform` 平台层、`model` 模型层                              | `platform`               |
| `x-praxis-recovery-action`   | 建议的处理动作                                                               | `relogin`                |

## 重试 [#重试]

* `retryable` 为 `true`（或状态码 `429` `502` `503`）：指数退避重试；`429` 优先按 `retry-after`。
* 其它一律不要原样重试——先改请求或 Key。