API 错误格式和错误代码

API 的每个错误响应都采用相同的格式。你的代码应依据 error 字段中的错误代码，而不是 message 中的文本：代码保持稳定，文本则可能变化，并会翻译成账户语言。

#错误响应的结构

{
  "error": "validation_failed",
  "message": "Some of the information provided is invalid. Please check and try again.",
  "details": [
    { "field": "title", "reason": "minLength", "message": "…" }
  ],
  "request_id": "6b1f0c2e-…"
}

error

机器可读的代码，例如 not_found。大多数错误还会在 X-Error-Code 响应头中给出，但请以响应体中的字段为准。

message

人类可读的描述，使用账户语言：使用 API 密钥时为工作区所有者的语言，使用已连接的应用时为连接该应用的人的语言。没有有效令牌时（例如令牌检查产生的 401），语言遵循 Accept-Language，否则为英文。Content-Language 响应头会注明所用的语言。

details

只在有更多信息时出现。输入校验产生的 422 是一个列表，每个问题都有 field、reason 和 message；业务逻辑产生的 422 以及所有其他错误则是一个对象，例如包含 reason、retry_after_sec 或 issues 列表。超出大小时，它包含 field、reason 和 limit，413 request_too_large 则包含 max_bytes 和 max_kb。所以请检查 details 是否为列表。

request_id

请求的 ID，也在 X-Request-Id 响应头中。联系支持团队时请附上它。

例外情况：429 rate_limited 响应用 retry_after_sec 字段代替 details；429 和 403 insufficient_scope 的响应体中没有 request_id。令牌检查产生的 401 和结构校验产生的 422 没有 X-Error-Code 响应头；结构校验时只有顶层的 message 会被翻译，details 中的文本保持英文。X-Request-Id 响应头则始终存在。

#最重要的代码

#读取输入错误

出现 422 validation_failed 时，details 会分别列出每个问题：field 是字段路径（嵌套对象用斜杠分隔，例如 theme_config/button_style），reason 是被违反的规则，例如 required、minLength、maxLength、enum 或 additionalProperties。出现 additionalProperties 时，message 会说明哪些字段是未知的，原因通常是字段名拼写错误。

#代码中的推荐处理方式

• 400、413 和 422：不要重试，而是修正请求
• 401 invalid_token：获取一次新令牌后重试
• 403：不要重试；检查权限范围、套餐或谁有权执行此操作
• 404：检查 ID；删除之后出现这个错误是正常的
• 409：重新加载状态，再判断这个操作是否仍然需要
• 429：按 Retry-After 给出的时间等待后重试，参见速率限制
• 500 和 503：以逐渐延长的间隔重试几次