错误代码

所有错误均遵循 RFC 7807。响应体类型为 application/problem+json，字段包括 type、title、status、detail、request_id，以及可选的 reason 或 errors[]。

{
  "type": "https://www.kernelhost.com/en/kernelhost-api/errors/payment_required",
  "title": "Payment required",
  "status": 402,
  "detail": "The order could not be paid.",
  "request_id": "01HX7Z3K8Q...",
  "reason": "insufficient_credit_and_no_card"
}

HTTP	type	含义
400	validation_failed	输入校验失败。具体字段错误请参见 errors[]。
401	auth_failed	认证失败。响应中的 reason 始终为 unauthorized（若密钥仅限其他 IP 地址使用，则为 ip_not_allowed），并有意不透露更多信息。请检查密钥、secret、时间（±300 秒）、nonce 和签名；技术支持可通过 request_id 查到具体原因。
402	payment_required	需要付款。具体 reason 请参见下文。
403	forbidden_scope	权限缺失。reason：missing_scope。
404	not_found	资源不存在或对该密钥不可见（防止租户枚举）。
409	idempotency_conflict, order_in_progress, service_not_active	冲突。可能是以下情况之一：该 Idempotency-Key 已用于不同的请求体或端点（idempotency_conflict；若首个请求仍在处理中，reason 为 in_progress）；您账户的另一笔订单仍在处理中（reason 为 order_in_progress，请遵循 Retry-After）；或者服务当前的状态不允许执行该操作（service_not_active，参见 service_status）。
413	payload_too_large	请求 body 超过 65,536 字节，在认证之前即被拒绝。
422	unprocessable	请求可理解但无法执行。reason billing_cycle_not_available：该产品不提供此计费周期。reason zero_total_not_allowed：在没有促销码等正当理由的情况下，该订单将变为免费。
429	rate_limited	超出速率限制。请遵循 Retry-After 响应头。
500	internal_error	内部服务器错误。联系技术支持时请提供 request_id 以便与审计日志关联。

Payment Required 原因（HTTP 402）

当订单无法完成付款时，API 返回 HTTP 402，并在 JSON 响应体中提供机器可读的 reason 字段。

• insufficient_credit_and_no_card (余额不足且未绑定信用卡。解决方法：充值余额或在客户门户中添加信用卡。)
• card_declined (信用卡被银行或支付网关拒绝。解决方法：尝试其他信用卡或联系您的银行。)
• credit_apply_failed (无法将余额应用到账单。未扣除任何费用，订单已取消。请使用新的 Idempotency-Key 重试或联系技术支持。)
• client_not_found (未找到账户 ID（实际几乎不会发生，请联系技术支持）。)