处理方法
- 请根据 HTTP 状态和 error.code 分支处理，不要依赖面向人的 error.message。
- 401 要求有效身份验证；403 要求调整访问权限或套餐；409 要求检查冲突操作或资源版本。
访问被拒绝与重试
- 401
- 401 并不总是表示令牌已过期。如果已过期，获取新令牌后最多重试读取一次。如果获取令牌返回 401，请检查密钥并停止自动尝试。
- 403
- 遇到 403 时，请检查权限、IP 限制和套餐。获取新令牌不会恢复已撤销的访问权限。
重试策略
- 对于临时故障，使用次数受限、逐步延长等待并带随机抖动的重试。
- 有 Retry-After 时应遵守。
- 写入超时时，其结果可能未知：重试同一逻辑操作时，保留原来的 Idempotency-Key 和未修改的请求。
- 下方目录解释所有已公开的错误代码。
422 / 409
- 对于价格，无效的货币格式或金额精度会返回 422 request.validation_failed。
- 有效的货币代码若与所选价格表不一致，则返回 409 resource.version_conflict。
- 重试前请检查上下文和版本。
错误目录
400request.malformed无法解析请求。
- 处理方法
- 检查 JSON 语法、URL 编码及请求结构。
- 重试策略
- 修正请求后重试。
{
"error": {
"code": "request.malformed",
"fields": null,
"message": "The request could not be read."
},
"meta": {
"request_id": "example-request"
}
}
401authentication.invalid_credentialsAPI 密钥或访问令牌无效、过期或已撤销。
- 处理方法
- 检查商店 URL 和凭据。使用有效 API 密钥获取新令牌。
- 重试策略
- 修正身份验证后重试；避免反复发送无效令牌请求。
{
"error": {
"code": "authentication.invalid_credentials",
"fields": null,
"message": "The credentials are invalid."
},
"meta": {
"request_id": "example-request"
}
}
401authentication.required缺少所需的 Authorization 请求头，或其方案不正确。
- 处理方法
- 获取令牌时使用 ApiKey，资源操作使用 Bearer。
- 重试策略
- 提供正确请求头后重试。
{
"error": {
"code": "authentication.required",
"fields": null,
"message": "Authentication is required."
},
"meta": {
"request_id": "example-request"
}
}
403authorization.client_ip_unverified服务无法确定可信的客户端 IP 地址。
- 处理方法
- 请商店运维人员检查入口链路。不要自行添加转发请求头。
- 重试策略
- 恢复可信连接链路后重试。
{
"error": {
"code": "authorization.client_ip_unverified",
"fields": null,
"message": "The client IP address could not be verified."
},
"meta": {
"request_id": "example-request"
}
}
403authorization.ip_not_allowed源 IP 地址不在密钥允许的地址列表中。
- 处理方法
- 使用获准的源地址，或请获授权的管理员编辑密钥 IP 列表。
- 重试策略
- 只有在地址获准后才重试。
{
"error": {
"code": "authorization.ip_not_allowed",
"fields": null,
"message": "Access from this IP address is not allowed."
},
"meta": {
"request_id": "example-request"
}
}
403authorization.scope_denied密钥不具备此操作所需的有效权限。
- 处理方法
- 检查操作所需的权限及条件权限、密钥授权和签发者的访问权限。
- 重试策略
- 获授权的管理员授予所需权限后再重试。
{
"error": {
"code": "authorization.scope_denied",
"fields": null,
"message": "The required permission has not been granted."
},
"meta": {
"request_id": "example-request"
}
}
403entitlements.api_disabled此商店的 API 访问已禁用。
- 处理方法
- 请店主检查当前套餐及 API 可用性。
- 重试策略
- 启用 API 访问前不要重试。
{
"error": {
"code": "entitlements.api_disabled",
"fields": null,
"message": "API access is disabled for this store."
},
"meta": {
"request_id": "example-request"
}
}
403entitlements.limit_exceeded变更会超出当前套餐的限制。
- 处理方法
- 检查适用资源限制，并调整计划的变更或套餐。
- 重试策略
- 解决限制后重试；若请求改变，请使用新的幂等键。
{
"error": {
"code": "entitlements.limit_exceeded",
"fields": null,
"message": "The operation exceeds a plan limit."
},
"meta": {
"request_id": "example-request"
}
}
403entitlements.operation_disabled当前套餐不包含此操作。
- 处理方法
- 检查该操作注明的最低套餐。
- 重试策略
- 套餐允许操作且密钥具有所需权限后再重试。
{
"error": {
"code": "entitlements.operation_disabled",
"fields": null,
"message": "The current plan does not allow this operation."
},
"meta": {
"request_id": "example-request"
}
}
403entitlements.resource_blocked套餐限制阻止访问此资源。
- 处理方法
- 请店主解决该资源的套餐限制。
- 重试策略
- 资源仍被阻止时，不要重复相同请求。
{
"error": {
"code": "entitlements.resource_blocked",
"fields": null,
"message": "A plan limit blocks access to this resource."
},
"meta": {
"request_id": "example-request"
}
}
404resource.not_found资源不存在、已删除，或无法通过给定标识符访问。
- 处理方法
- 检查商店、资源路径和标识符。使用此商店返回的标识符。
- 重试策略
- 修正目标或确认目标存在后才重试。
{
"error": {
"code": "resource.not_found",
"fields": null,
"message": "The resource was not found."
},
"meta": {
"request_id": "example-request"
}
}
405request.method_not_allowed端点不支持此 HTTP 方法。
- 处理方法
- 使用文档规定的方法；Allow 响应头列出支持的方法。
- 重试策略
- 不要重试不支持的方法。
{
"error": {
"code": "request.method_not_allowed",
"fields": null,
"message": "This method is not supported for this resource."
},
"meta": {
"request_id": "example-request"
}
}
409idempotency.key_reused此幂等键属于另一个请求。
- 处理方法
- 查找原始操作。只有确实要进行新的逻辑操作时，才使用新密钥。
- 重试策略
- 不要使用冲突的密钥重试已改变的请求内容。
{
"error": {
"code": "idempotency.key_reused",
"fields": null,
"message": "This idempotency key was used with a different request."
},
"meta": {
"request_id": "example-request"
}
}
409resource.already_exists唯一值与现有资源冲突。
- 处理方法
- 读取现有资源，决定使用它还是选择其他唯一值。
- 重试策略
- 不要重复相同的冲突创建操作。
{
"error": {
"code": "resource.already_exists",
"fields": null,
"message": "A resource with these unique values already exists."
},
"meta": {
"request_id": "example-request"
}
}
409resource.in_use其他资源仍依赖此资源。
- 处理方法
- 检查依赖关系；删除前，通过支持的操作移除或修改依赖。
- 重试策略
- 处理依赖关系后重试。
{
"error": {
"code": "resource.in_use",
"fields": null,
"message": "The resource is still in use."
},
"meta": {
"request_id": "example-request"
}
}
409resource.state_conflict当前业务状态阻止此变更。
- 处理方法
- 读取当前状态并选择有效的业务状态转换。
- 重试策略
- 不要自动强制执行或反复提交冲突变更。
{
"error": {
"code": "resource.state_conflict",
"fields": null,
"message": "The current resource state does not allow this operation."
},
"meta": {
"request_id": "example-request"
}
}
409resource.version_conflict在你读取版本后，另一次写入改变了资源。
- 处理方法
- 读取最新状态，协调变更，再提交新的 expected_version。
- 重试策略
- 为调整后的操作使用新的幂等键；不要盲目覆盖。
{
"error": {
"code": "resource.version_conflict",
"fields": null,
"message": "The resource version has changed."
},
"meta": {
"request_id": "example-request"
}
}
413request.too_large请求超出大小限制。
- 处理方法
- 减小请求内容，或将工作拆分为支持的独立操作。
- 重试策略
- 使用各自的幂等键重试更小且有效的操作。
{
"error": {
"code": "request.too_large",
"fields": null,
"message": "The request exceeds the size limit."
},
"meta": {
"request_id": "example-request"
}
}
415request.unsupported_media_type不支持该媒体类型或内容编码。
- 处理方法
- JSON 写入使用 Content-Type: application/json，并发送受支持的未压缩请求体。
- 重试策略
- 修正媒体类型或编码后重试。
{
"error": {
"code": "request.unsupported_media_type",
"fields": null,
"message": "The request media type or encoding is not supported."
},
"meta": {
"request_id": "example-request"
}
}
422request.validation_failed一个或多个字段或参数未通过验证。
- 处理方法
- 查看 error.fields，再检查必填字段、是否允许 null、标识符和允许值。
- 重试策略
- 修正请求后重试；已改变的写入属于新的逻辑操作。
{
"error": {
"code": "request.validation_failed",
"fields": null,
"message": "Some request parameters are invalid."
},
"meta": {
"request_id": "example-request"
}
}
429capacity.queue_fullAPI 短队列已满；请求尚未开始执行。
- 处理方法
- 将请求排入队列，并遵守 Retry-After 响应头。
- 重试策略
- 至少等待 Retry-After 秒，并增加随机延迟。重试写入时保留原始密钥和请求内容。
{
"error": {
"code": "capacity.queue_full",
"fields": null,
"message": "The API is busy. Please retry shortly."
},
"meta": {
"request_id": "example-request"
}
}
429capacity.wait_timeoutAPI 队列等待超时；请求尚未开始执行。
- 处理方法
- 将请求排入队列，并遵守 Retry-After 响应头。
- 重试策略
- 至少等待 Retry-After 秒，并增加随机延迟。重试写入时保留原始密钥和请求内容。
{
"error": {
"code": "capacity.wait_timeout",
"fields": null,
"message": "The API could not start this request in time. Please retry shortly."
},
"meta": {
"request_id": "example-request"
}
}
429rate_limit.exceeded请求速率超出适用限制。
- 处理方法
- 将请求排入队列，并遵守 Retry-After 响应头。
- 重试策略
- 至少等待 Retry-After 秒，并增加随机延迟。重试写入时保留原始密钥和请求内容。
{
"error": {
"code": "rate_limit.exceeded",
"fields": null,
"message": "The request rate limit has been exceeded."
},
"meta": {
"request_id": "example-request"
}
}
500internal.error发生意外服务错误。
- 处理方法
- 记录请求标识符；错误持续时联系运维人员。日志中不得包含凭据。
- 重试策略
- 使用次数受限的退避重试。写入时保留原始幂等键和未修改的内容。
{
"error": {
"code": "internal.error",
"fields": null,
"message": "An unexpected error occurred."
},
"meta": {
"request_id": "example-request"
}
}
502gateway.bad_response网关未收到有效的 API 响应。
- 处理方法
- 保留请求标识符。失败响应不代表写入未被执行。
- 重试策略
- 使用次数受限的退避重试；重复同一逻辑写入时，保留原始 Idempotency-Key 和请求内容。
{
"error": {
"code": "gateway.bad_response",
"fields": null,
"message": "The API gateway could not obtain a valid response."
},
"meta": {
"request_id": "example-request"
}
}
504gateway.timeout网关等待 API 响应超时。
- 处理方法
- 保留请求标识符，并将写入结果视为未知。
- 重试策略
- 使用次数受限的退避重试；写入时复用原始幂等键和未修改的内容。
{
"error": {
"code": "gateway.timeout",
"fields": null,
"message": "The API gateway timed out."
},
"meta": {
"request_id": "example-request"
}
}