错误码

同步错误采用 error.message/type/param/code 结构；异步失败采用内部标准错误结构，需要单独处理。

同步错误结构

{
  "error": {
    "message": "billing error",
    "type": "billing_error",
    "param": null,
    "code": "insufficient_credits"
  }
}

HTTP	type	说明
400	`invalid_request_error`	请求参数错误
401	`authentication_error`	鉴权失败，框架支持
402	`billing_error`	计费或余额问题
403	`permission_error`	无权限、安全拦截、当前 AGW API Key 失败常见落点
404	`not_found_error`	资源不存在
409	`conflict_error`	资源冲突
429	`rate_limit_error`	限流或并发超限
500/502/503/504	`internal / upstream / service / timeout`	系统、下游、服务不可用或超时

常见 code

code	说明
`missing_required_field`	缺少必填字段
`invalid_field_value`	字段值不合法
`unsupported_response_format`	不支持的输出格式
`invalid_url` / `url_not_allowed`	URL 格式不合法或不允许访问
`insufficient_credits`	余额不足
`rate_limit_exceeded` / `concurrency_limit_exceeded`	请求频率或并发超限
`file_not_found` / `voice_not_found` / `task_not_found`	资源不存在
`safety_guardrail_blocked`	安全检测拦截

异步失败结构

异步任务失败时 status 为 FAILED，error 是内部标准错误结构，与同步错误结构不同。

{
  "id": "task-xxx",
  "object": "audio.speech",
  "status": "FAILED",
  "error": {
    "error_code": 16001,
    "error_msg": "billing error",
    "internal_error_code": 109111005,
    "internal_error_msg": "insufficient credits"
  }
}