跳到主要内容

错误处理

税鹰眼 API 使用标准 HTTP 状态码和结构化错误响应。

错误响应格式​

{
  "detail": "错误描述信息"
}

HTTP 状态码​

成功响应​

状态码说明
200 OK请求成功
202 Accepted已接受（异步处理中）
204 No Content操作成功，无返回体（如删除）

客户端错误 (4xx)​

状态码说明处理建议
400 Bad Request请求体格式错误或参数无效检查请求参数
401 UnauthorizedAPI Key 无效或缺失检查密钥配置
404 Not Found资源不存在确认 ID 正确
422 Unprocessable Entity数据校验失败查看 detail 修正数据
429 Too Many Requests超出速率限制等待 Retry-After 后重试

服务端错误 (5xx)​

状态码说明处理建议
500 Internal Server Error服务器内部错误稍后重试，如持续报错请联系支持
503 Service Unavailable服务暂时不可用等待后重试

常见错误场景​

数据校验错误 (422)​

{
  "detail": [
    {
      "loc": ["body", "years_data", 0, "sheets", 0, "items"],
      "msg": "至少需要一条数据项",
      "type": "value_error"
    }
  ]
}

资源不存在 (404)​

{
  "detail": "报告不存在"
}

速率限制 (429)​

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": "Rate limit exceeded: 100 per 1 minute"
}

重试策略​

建议实现指数退避 (Exponential Backoff)：

import time
import httpx

def api_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = httpx.get(url, headers=headers)

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            continue

        if response.status_code >= 500:
            wait = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait)
            continue

        return response

    raise Exception("Max retries exceeded")

错误排查清单​

  1. ✅ API Key 是否正确（包含 ek_live_ 或 ek_test_ 前缀）
  2. ✅ Header 名称是否为 X-API-Key（区分大小写）
  3. ✅ Content-Type 是否为 application/json
  4. ✅ 请求体是否为合法 JSON
  5. ✅ 必填字段是否完整
  6. ✅ 数字字段是否为字符串格式（如 "10000.00"）