错误

{
  "code": "insufficient_balance",
  "error": "Not enough funds",
  "request_id": "9f3c1e2a7b4d5e60"
}

请根据 code 分支处理。部分错误带有额外字段：

{
  "code": "invalid_targeting",
  "error": "Unknown city",
  "field": "city",
  "value": "nosuchcity"
}
{
  "code": "unsupported_field",
  "error": "Field is not supported here",
  "field": "count"
}
{
  "code": "rate_limited",
  "error": "Too many requests",
  "retry_after": 12,
  "limit": 120
}

GET /api/v1/orders/{id} 的 404 只包含 error 和 request_id，没有 code。

代码目录

代码	状态	何时
invalid_api_key	401	密钥未被接受
validation_failed	400	违反了字段约束
invalid_body	400	请求体或字段格式不正确
unknown_product	400	slug 未知或产品不在售
insufficient_scope	403	密钥缺少该路由所需的权限
not_found	404	资源不存在或属于其他账户
idempotency_in_progress	409	使用该键的上一个请求仍在执行
replace_in_progress	409	套餐的地址更换已在进行中
invalid_volume	422	流量超出产品允许的范围
invalid_quantity	422	地址数量超过单次购买上限
country_unavailable	422	该产品在此国家不在售
unknown_plan, unknown_operator, unknown_period	422	所选国家没有该方案、位置或周期 - 请核对参数
out_of_stock	422	该位置的可用地址少于请求数量
unsupported_capability	422	该操作不适用于此类套餐
package_expired	422	地址套餐已到期 - 请先续期
prolong_window_closed	422	已无法通过续期恢复地址 - 需要重新购买
type_unavailable	422	该配置既无法报价也无法出售
insufficient_balance	422	余额不足
unsupported_field	422	请求体中有不适用的键；附带 field
invalid_targeting	422	该值不在地理目录中；附带 field 和 value
package_unavailable	422	在套餐当前状态下或使用这些设置时无法执行该操作
purchase_refunded	422	购买未完成，资金已退回
idempotency_key_required	422	缺少 Idempotency-Key 请求头
idempotency_key_invalid	422	请求头为空或超过 255 个字符
idempotency_key_reused	422	同一个键搭配了不同的请求体
rate_limited	429	密钥的请求配额已用完
replace_cooldown	429	地址最近已更换过；何时可再次更换见 replace_available_at
order_failed	500	订单未创建，余额未扣除
package_failed	500	套餐操作失败，资金未扣除
order_needs_attention	500	资金已扣除，交付未完成，正在人工处理
operation_indeterminate	500	使用了一个结果未确定的操作的键重试
catalog_unavailable	503	该产品的地理目录尚未同步

付费操作

代码	资金	处理方式
order_failed, package_failed	未扣除	使用相同的 Idempotency-Key 重试
purchase_refunded (422)	已退回	使用新键作为新购买重试
order_needs_attention	已扣除，结果待确认	不要重试，携带 order_id 联系客服
operation_indeterminate	结果未确定	不要使用同一个键重试；先核对订单和套餐，再联系客服

5xx 中的消息是通用文本 - 请根据 code 分支处理。

客服支持：@ipvrent_support， [email protected]。请附上错误响应体中的 request_id，如有 order_id 也请一并附上。

重试

超时不等于失败：请求可能已经送达。使用相同的 Idempotency-Key 重试会返回相同的响应。 遇到 409 idempotency_in_progress 时，请等待后使用同一个键重试。

以下错误不应重试： insufficient_balance, invalid_volume, invalid_quantity, unknown_product, unsupported_field, unsupported_capability, invalid_targeting, prolong_window_closed。遇到 rate_limited 时等待 Retry-After，遇到 replace_cooldown 时等待 replace_available_at。