错误码
PolyTest API 使用标准 HTTP 状态码。所有错误响应都会返回一个 JSON 主体，其中的 error 字段描述了问题。
错误响应格式：所有错误都返回一个 JSON 对象，其中只有一个
"error" 键，包含一条易读的消息。HTTP 状态码表示错误类别。400Bad Request
请求格式错误或缺少必填参数。
{ "error": "timestamp query parameter is required" }常见原因
- 缺少必填的查询参数
- 参数格式无效（例如时间戳不是 ISO 8601 格式）
- 参数值超出允许范围
401Unauthorized
认证失败：请求没有有效的凭证。
{ "error": "Invalid API key" }常见原因
- 缺少 X-API-Key 请求头或 Authorization 请求头
- API 密钥不存在或无效
- API 密钥已被撤销
- API 密钥已过期
- JWT 令牌无效或已过期
403Forbidden
凭证有效，但没有执行此操作的权限。
{ "error": "Admin access required" }常见原因
- 在没有管理员权限的情况下尝试访问仅限管理员的端点（sync、seed）
- API 密钥的权限范围不包含所需权限
404Not Found
请求的资源不存在。
{ "error": "Market not found" }常见原因
- 市场 ID 不存在
- 市场 slug 没有匹配的记录
- 在给定时间戳 ±2 秒内没有找到快照
429Too Many Requests
超出速率限制。请退避，并在指示的时间后重试。
{ "error": "Rate limit exceeded" }常见原因
- 超出你的套餐档位的每分钟请求数限制
- 超出突发限制（短时间内请求过多）
500Internal Server Error
服务器发生意外错误。这种情况很少见，如果持续出现，请联系支持。
{ "error": "Internal server error" }常见原因
- 数据库连接问题
- 上游服务故障
- 服务器端意外异常
处理错误
客户端错误（4xx）
不要自动重试。重试前请先修正请求参数或认证，或确认资源是否存在。
服务器错误（5xx）
可以安全地使用指数退避重试。从 1 秒延迟开始，每次重试翻倍，最多重试 3 次。
import time
import requests
def api_request(url, headers, max_retries=3):
for attempt in range(max_retries):
response = requests.get(url, headers=headers)
if response.status_code == 429:
wait = int(response.headers.get("Retry-After", 2 ** attempt))
time.sleep(wait)
continue
if response.status_code >= 500:
time.sleep(2 ** attempt)
continue
return response
raise Exception("Max retries exceeded")