错误码

请求失败时 HTTP 状态码与 message 字段说明如下。

错误响应体

业务错误始终返回机器可读的 code，便于程序化分支处理：

{
  "code": "insufficient_balance",
  "message": "Insufficient balance for this submission."
}

错误码对照表

code	HTTP	说明
`unauthorized`	401	API Key 缺失、无效或已停用。
`account_banned`	403	账号已被封禁，请联系客服。
`invalid_realtime_request`	400	实时检测请求格式错误（例如 country 留空时号码缺少 `+` 国际区号前缀）。
`idempotency_key_required`	400	实时检测请求必须携带 `Idempotency-Key` 头。
`invalid_idempotency_key`	422	`Idempotency-Key` 格式非法：仅允许 1-128 位字母、数字及 `. _ : -` 字符。
`idempotency_conflict`	409	同一 `Idempotency-Key` 被用于内容不同的请求。
`request_in_progress`	409	完全相同的实时请求正在处理中，请稍后重试（`Retry-After: 1`）。
`empty_input`	422	上传的文件没有可用数据行。
`product_not_found`	422	提交的产品 slug 不存在或未启用。
`product_mode_not_supported`	422	该端点不接受此产品模式（实时产品不能提交到批量端点）。
`invalid_country`	422	该产品不支持所提交的国家。
`too_few_numbers`	422	提交数量低于该产品的最低起量。
`too_many_numbers`	422	提交数量超过平台上限。
`insufficient_balance`	402	余额不足以覆盖本次提交，请充值后重试。
`realtime_disabled`	403	该账号未开通实时检测。
`realtime_rate_limited`	429	实时检测触发限流，请遵循 `retry_after`。
`product_pricing_unavailable`	503	该产品尚未配置价格，请联系客服。
`detection_capacity_unavailable`	503	当前没有可用检测通道容量，请稍后重试。
`realtime_route_unavailable`	503	当前没有可用的实时检测路由，请稍后重试。
`realtime_fact_cache_unavailable`	503	实时检测依赖服务暂时不可用，请稍后重试。
`realtime_rate_limiter_unavailable`	503	限流器暂时不可用，请稍后重试。
`internal_error`	500	服务器内部错误。携带相同 `Idempotency-Key` 重试是安全的。