交换 API 错误处理

​

HTTP 状态码

​

2xx：成功

• 200 OK：请求成功，服务器返回了预期的响应。

​

4xx：客户端错误

• 400 Bad Request：请求格式错误或包含无效参数。
• 401 Unauthorized：Bearer API 密钥缺失或无效（在 API 密钥强制校验开启后返回）。
• 403 Forbidden：客户端无权访问所请求的资源。
• 404 Not Found：找不到所请求的资源。
• 429 Too Many Requests：客户端已超出允许的速率限制。

​

5xx：服务器错误

• 500 Internal Server Error：服务器发生了意外错误。
• 502 Bad Gateway：服务器从上游服务器收到了无效响应。
• 503 Service Unavailable：服务暂时不可用，可能因维护或过载导致。

​

错误响应格式

​

应用错误

{
  "error_code": "PAIR_NOT_FOUND",
  "message": "Trading pair not found: BTC/USDT",
  "details": {},
  "request_id": "req_01HV8Q9X7G0Q7Y3Z"
}

• error_code（string）：稳定的、机器可读的错误码（例如 PAIR_NOT_FOUND、VALIDATION_ERROR、NOT_FOUND、RATE_LIMIT_EXCEEDED、INTERNAL_ERROR）。
• message（string）：错误的可读描述。
• details（object）：关于该错误的可选结构化上下文（可能为空）。
• request_id（string）：请求关联标识符 —— 联系支持团队时请一并提供。

​

请求校验错误（HTTP 422）

{
  "detail": [
    {
      "loc": ["body", "rfq_id"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

• detail（array<object>）：每个校验失败对应一个条目。
  • loc（array<(string | integer)>）：出错字段的路径。
  • msg（string）：校验错误信息。
  • type（string）：FastAPI/Pydantic 校验错误类型。

​

遗留错误

{
  "detail": "Route not supported for this pair. From: BTC_LN, To: RGB_LN"
}

• detail（string）：错误的可读描述。

​

常见错误

​

400 Bad Request

• 原因：请求中参数缺失或无效。
• 解决办法：核对请求载荷，确保所有必填字段都已提供且数据有效。

​

404 Not Found

• 原因：请求的接口端点或资源不存在。
• 解决办法：检查接口端点 URL 和资源标识符。

​

429 Too Many Requests

• 原因：客户端在短时间内发送了过多请求。
• 解决办法：在客户端应用中实现速率限制，并在指定的等待时间（如有提供）后重试。

​

500 Internal Server Error

• 原因：服务器发生了意外错误。
• 解决办法：稍后重试请求。如果问题持续存在，请携带请求详情联系支持团队。

​

WebSocket 错误处理

​

重连策略

1. 等待数秒（例如 5-10 秒）。
2. 重新建立连接。
3. 重新发送所有待处理的 quote_request 消息，以获取最新报价。

​

调试建议

1. 查看日志：监控应用日志，获取失败请求的详细信息。
2. 校验输入：确保所有请求参数和载荷都符合 API 要求。
3. 联系支持：对于持续出现或原因不明的错误，请提供以下信息：
   • 请求 URL
   • HTTP 方法
   • 请求载荷
   • 错误发生的时间戳
   • API 返回的完整错误响应

​

最佳实践

1. 优雅处理错误：在应用中实现完善的错误处理逻辑，避免崩溃或影响用户体验。
2. 速率限制：遵守 API 速率限制，避免出现 429 Too Many Requests 错误。
3. 重试机制：对于瞬时错误（例如 500 Internal Server Error），请实现带指数退避的重试机制。