开发文档
请求不如预期时
清晰的输入、审慎的请求标识、如实呈现的结果。这是集成网关时需要了解的基础。
超时不等于执行失败
操作可能在响应丢失前已经执行。不要自动用新标识重放付费 POST。请检查用量记录并保留原始 Idempotency-Key。
| HTTP | 错误码 | 处理方式 |
|---|---|---|
| 400 | INVALID_PARAM | 检查该操作文档中的字段位置、必填值、类型和限制。 |
| 401 | AUTH_FAILED | 密钥缺失、无效、已过期或已撤销。请勿在日志中暴露密钥。 |
| 402 | INSUFFICIENT_CREDITS | 钱包可用余额不足以支付此请求。 |
| 403 | SCOPE_DENIED | 使用明确允许此操作的密钥。 |
| 403 | ACCOUNT_FROZEN | 新计费请求已被阻止，请检查账户和付款状态。 |
| 409 | IDEMPOTENCY_CONFLICT | 此请求标识已用于不同输入，请勿修改已有请求意图。 |
| 429 | RATE_LIMITED / CONCURRENCY_LIMIT | 遵守 Retry-After，并保留原始请求标识。 |
| 503 | NOT_CONFIGURED / OPERATION_DISABLED | 服务或操作不可用。请在 API 页面查看该操作的当前可用状态。 |
预留、扣款与释放不是同一回事
请求结果待定时可能预留积分。确认成功后结算预留，确认失败后释放。不确定结果可能保留预留以待核对。可用余额与账面余额不同，不要将临时预留视作已成功扣款。
保留证据，而非密钥
联系支持时保留请求 ID、操作、时间及错误码。不要包含明文密钥、会话 Cookie、支付凭证或未脱敏的个人输入。SERVICE_UNAVAILABLE 与 SERVICE_BUSY 描述的是服务端状况，与你的钱包余额无关。