SMSBulk
返回文档
错误参考

错误与速率限制

错误代码、HTTP 状态映射、速率限制策略和重试策略的完整参考。

HTTP 状态码

现代 REST API 使用标准 HTTP 状态码。响应体包含结构化的错误对象。

代码状态含义
400Bad Request请求验证失败(参数缺失或无效)
401Unauthorized需要身份验证或 API 密钥无效
402Payment Required钱包余额不足以完成操作
403Forbidden已认证但无权访问此资源
404Not Found资源未找到(例如激活 ID 不存在)
409Conflict请求与当前状态冲突
422Unprocessable Entity请求格式正确但语义无效
429Too Many Requests速率限制超限 — 查看 Retry-After 响应头
500Internal Server Error意外服务器错误 — 用指数退避重试
503Service Unavailable上游服务暂不可用 — 稍后重试

错误响应形式(JSON)

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 27937
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-05-10T00:00:00.000Z

{
  "error": "rate_limit_exceeded",
  "message": "Daily API limit reached. Contact support for higher tier.",
  "retryAfter": 27937,
  "limit": 10000,
  "usage": 10000
}

SMS-Activate 文本代码

SMS-Activate 兼容端点返回纯文本代码。每个代码映射到一个 HTTP 状态。

文本代码HTTP含义
BAD_KEY401API 密钥无效或缺失
BAD_ACTION400action 参数缺失或格式错误
BAD_SERVICE400服务代码无法识别
BAD_COUNTRY400country 参数无法识别
BAD_STATUS400setStatus 的 status 值无效
WRONG_ACTION400不支持的操作名
NO_BALANCE402钱包余额不足
NO_NUMBERS404此组合没有可用号码
NO_ACTIVATION404激活 ID 不存在或不属于你
RATE_LIMITED429速率限制超限 — 减速或等待重置
ERROR_SQL500服务器内部错误 — 稍后重试

速率限制

按 API 密钥限流。多个服务器使用同一密钥共享一个桶。

突发限制

三层并发限流保护防止突发和持续滥用。达到任何一层返回 429。

short
5
/ 1 second
medium
30
/ 10 seconds
long
100
/ 60 seconds

每日配额

默认每个 API 密钥每天 10,000 次请求。UTC 午夜重置。

  • 公共目录端点(services、countries)免于每日配额
  • 配额计数器在每个已认证请求时增加,无论响应状态
  • 提供更高限额的 Pro 级别 — 联系支持

响应头

每个已认证 API 响应都包含速率限制响应头,客户端可以主动自我限流。

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9543
X-RateLimit-Reset: 2026-05-10T00:00:00.000Z
Retry-After: 27937

重试策略

如何在不过载 API 或丢失数据的前提下处理瞬态故障。

应当

  • • 在 429 响应中遵守 Retry-After 头
  • • 对 5xx 错误使用指数退避(1秒、2秒、4秒、8秒)
  • • 重试最多 5 次,然后向用户显示错误

不应

  • • 不要重试 429 以外的 4xx 错误 — 它们是确定性的
  • • 429 后不要持续敲击 API — 等待完整的 Retry-After 时间
  • • 不要在不检查幂等性的情况下重试 POST /activations

推荐的重试模式

# Pseudocode — exponential backoff with Retry-After
attempt = 0
while attempt < 5:
    response = call_api()

    if response.status == 200:
        break  # success

    if response.status == 429:
        wait = response.headers.get('Retry-After', 2 ** attempt)
        sleep(wait)
        attempt += 1
        continue

    if response.status >= 500:
        sleep(2 ** attempt)  # exponential
        attempt += 1
        continue

    raise APIError(response)  # 4xx other than 429

幂等性

某些操作会从钱包扣费 — 简单重试可能导致重复扣款。

POST /activations 非幂等

如果你重试一个成功的 POST /activations,会创建第二次激活并被收费两次。任何超时或不明响应时,先用 GET /activations 验证状态再重试。

需要更多细节?

交互式 API 参考显示每个端点的错误响应。

返回文档打开 API 参考