错误码

SubHub API 使用标准 HTTP 状态码与结构化 error 对象。

错误响应格式

{
  "error": {
    "type": "invalid_request_error",
    "code": "receipt_invalid",
    "message": "The provided receipt could not be verified.",
    "param": "receipt"
  }
}

HTTP 状态码

状态码	说明
200	请求成功
400	请求参数无效
401	认证失败 — 检查 Secret Key
403	权限不足
404	资源不存在
409	冲突 — 如重复验证
429	请求频率超限
500	平台内部错误
503	Provider 暂时不可用

错误码列表

code	说明	处理建议
invalid_api_key	API 密钥无效	检查 Authorization 头
receipt_invalid	凭证验证失败	确认 receipt 未过期
receipt_already_used	凭证已验证	幂等处理，返回已有 Purchase
product_not_found	Product 不存在	检查 product_id
member_not_found	Member 不存在	确认 member_id 有效
provider_unavailable	Provider API 不可用	稍后重试
provider_rejected	Provider 拒绝交易	检查 Sandbox/Live 环境
entitlement_not_found	Entitlement 不存在	确认 identifier
rate_limit_exceeded	超出频率限制	降低请求频率，查看 Retry-After
webhook_signature_invalid	Webhook 签名无效	检查 Webhook Secret

幂等性

POST /v1/purchases/verify 支持 Idempotency-Key 请求头。相同 key 的重复请求返回相同结果，不会重复写入。

POST /v1/purchases/verify
Authorization: Bearer sk_live_...
Idempotency-Key: idem_purchase_abc123
Content-Type: application/json