> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaleidoswap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 交换 API 错误处理

> 了解 KaleidoSwap API 如何报告错误：HTTP 状态码、错误响应格式，以及构建高可用集成的处理策略与重试建议。

KaleidoSwap API 使用标准 HTTP 状态码和详细的错误信息来传达 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**：服务暂时不可用，可能因维护或过载导致。

***

## 错误响应格式

API 会根据请求失败的位置返回**三种不同的错误信封**。

### 应用错误

业务与应用错误（参数无效、资源缺失、冲突、速率限制、服务器错误）返回结构化信封：

```json theme={null}
{
  "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）

在到达应用逻辑*之前*就未通过 schema 校验的请求，会返回 FastAPI 的校验信封，HTTP 状态码为 `422`：

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "rfq_id"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

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

### 遗留错误

少数接口端点的部分 `400` 响应仍是一个裸的 detail 对象，**不含** `error_code` 或 `request_id` —— 例如 `POST /market/quote` 上不受支持的路由，或 `GET /market/pairs` 上格式错误的 `pair_ticker` 过滤条件：

```json theme={null}
{
  "detail": "Route not supported for this pair. From: BTC_LN, To: RGB_LN"
}
```

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

处理 `400` 响应的客户端应同时兼容结构化信封和这种遗留形式。

***

## 常见错误

以下是一些典型错误及其解决办法：

### 400 Bad Request

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

### 404 Not Found

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

### 429 Too Many Requests

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

### 500 Internal Server Error

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

***

## WebSocket 错误处理

对于 WebSocket 连接，错误以 JSON 消息形式传达。如果发生严重错误，服务器可能会关闭连接。

### 重连策略

如果 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），请实现带指数退避的重试机制。

***

关于错误码和故障排查的更多细节，请参阅 API 文档。