错误处理 - APIAny.AI Docs

每个对话接口都返回与其兼容的 API 标准（OpenAI / Anthropic / Gemini）一致的错误结构。所有错误响应都带 X-Request-Id 响应头，只返回你排查请求所需的信息。

OpenAI — `/v1/chat/completions`（以及图片/视频接口）

{
  "error": {
    "message": "Insufficient credits",
    "type": "insufficient_quota",
    "code": "insufficient_credits",
    "param": null
  }
}

Anthropic — `/v1/messages`

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

Gemini — `/v1beta/models/{model}:generateContent`

{
  "error": {
    "code": 400,
    "message": "model is required",
    "status": "INVALID_ARGUMENT"
  }
}

状态码映射

错误的 type / status 由 HTTP 状态码推导：

HTTP	OpenAI `type`	Anthropic `type`	Gemini `status`
400	invalid_request_error	invalid_request_error	INVALID_ARGUMENT
401	authentication_error	authentication_error	UNAUTHENTICATED
403	permission_error	permission_error	PERMISSION_DENIED
404	not_found_error	not_found_error	NOT_FOUND
402	insufficient_quota	invalid_request_error	RESOURCE_EXHAUSTED
429	rate_limit_error	rate_limit_error	RESOURCE_EXHAUSTED
5xx	api_error	api_error / overloaded_error	SERVER_ERROR / UNAVAILABLE

模型参数被拒绝

当模型不接受请求中的某个取值时，接口返回 HTTP 400 并附带模型自己的说明。思考相关设置返回错误码 invalid_reasoning_effort，消息中会列出该模型接受的取值，便于直接改正而不必反复试错。每个模型支持的思考档位、默认档位以及能否关闭思考，都记录在 GET /v1/models 的 capability_metadata.reasoning 中。限流返回 429，超出时间预算的请求返回 504。502 表示平台在重试后仍未从模型获得可用答案，并不代表参数有问题，建议先读响应内容再调整参数。

媒体生成错误与重试

图片和视频生成应依据结构化的 error.code 和任务的 status（客户端中的 task.status）决定提示内容和是否重试。

错误码	含义与建议处理
`not_found`	在生成任务中可能表示未返回有效媒体，也可能是所请求的端点或资源不存在；不能据此判断内容违规。
`rate_limit`	可能是请求限流，也可能是模型服务暂时过载。等待后可有限重试，并逐步延长重试间隔。
`content_policy`、`content_filter`、`image_safety`	明确的内容策略拒绝，应提示用户修改内容。

只有明确的内容策略错误码或明确的内容策略拒绝，才应建议修改内容。不能仅凭错误消息提到 safety，或 HTTP 502，推断内容违规。异步任务仍为 pending 或 processing 时，继续使用同一个 task_id 查询 /v1/tasks/{task_id}，不要重复提交生成请求。