Docs

错误

最后更新: 2026-07-21阅读约 2 分钟

错误采用 RFC 7807 的 application/problem+json 格式，因此结构统一、便于程序解析：

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://docs.grem.capital/api/errors/validation",
  "title": "validation",
  "status": 400,
  "detail": "totalArea (m2) is required",
  "requestId": "req_…"
}

请始终记录 requestId — 向客服反馈时附上它，便于追踪这次调用。

状态码

状态含义该怎么做
400校验错误按 detail 修正请求体或参数。
401密钥无效或缺失检查 Authorization 请求头。
402余额或额度不足充值或升级套餐。
403缺少权限范围该密钥未被授权调用此工具。
404未找到路径有误，或资源不存在。
409幂等冲突使用同一 Idempotency-Key 的请求仍在进行中。
422业务规则请求本身合法，但当前无法照此处理。
429触发频率限制稍候重试 — 见频率限制。
5xx服务端错误属于临时问题；请以递增间隔重试。

被拒绝的请求（4xx）不计费 — 每次调用的费用只在成功时收取。

如何处理错误

  • 按数字型的 HTTP status 分支处理，而不要依赖 detail 中的可读文本。
  • 对 429 和 5xx 使用指数退避重试；不要重试 4xx（409 除外，可在进行中的请求结束后重试）。
  • 错误中绝不会泄露服务商的细节 — 故障会统一以 provider_error 呈现。

这篇文章对您有帮助吗？