错误

状态码说"哪一类"，错误体说"具体是什么"；错误响应提供五个通用头，限流时再带一个 scope 头，让重试逻辑不用看错误体。

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

状态码

状态码	含义	你该做什么
`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 错误体一模一样。

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

// /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。

{
  "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。

错误

状态码

错误码

错误体

错误响应头（五个通用头 + 一个限流头）

重试

本页内容