// 1. A plain message — most 400 / 401 / 403 / 404 responses
{ "detail": "Order not found" }

// 2. A coded error — newer endpoints (sub-users, gateways, whitelist removal).
//    Branch on detail.error.code; the message is for humans and may change.
{
  "detail": {
    "error": {
      "code": "insufficient_unallocated_traffic",
      "message": "not enough unallocated traffic on this service"
    }
  }
}

// 3. Request validation — always HTTP 422, one entry per rejected field
{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "gb"],
      "msg": "Value error, gb must be a whole number of GB (1, 2, 3, ...); got 1.5",
      "input": 1.5
    }
  ]
}

健壮的客户端会先读取状态码，再检查 detail 是否为包含 error.code 的对象，之后才回退为将其作为文本渲染。本参考中提到的错误码始终位于 detail.error.code。

状态	含义
400	请求错误——参数格式错误或缺失。
401	未授权——API 密钥缺失或无效。
404	未找到——此账户中不存在该资源。
409	冲突——请求与资源的当前状态冲突。
429	请求过多——超出速率限制。
500	服务器内部错误——请使用退避策略重试。

速率限制

请求限制为每个 IP 每分钟 600 次请求。超出限制将返回 429 状态码——请退避并在短暂延迟后重试。

幂等性

下单、续期、充值和子用户写入端点必须携带 Idempotency-Key 请求头——省略它会在任何扣费或创建发生之前返回 400。请为每个新请求发送一个唯一键（使用 UUID 即可）；在超时或网络错误后使用同一个键重试，可保证该操作最多只执行一次。

重放的请求会返回原始结果，并带有 Idempotent-Replayed: true 响应头，因此您可以区分可安全忽略的重试与全新的写入——无论哪种情况，响应体本身都完全相同。

有两个例外值得在代码中处理。子用户的 allocate 和 reclaim 不会重放：重复使用的键会返回 409 request_in_progress，而不是先前的结果，因此请为每次尝试使用新键，并重新读取子用户以确认状态。此外，如果重复使用的键所对应的子用户此后已被删除，将返回 409 idempotency_key_reused，而不是已失效的记录。