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

# 错误处理

> 了解错误码、响应格式和故障排除策略。

## 响应码

Legitmark 使用标准 HTTP 状态码来指示请求的成功或失败。
一般来说，2xx HTTP 状态码表示成功，4xx 状态码表示用户相关错误，5xx 状态码表示基础设施问题。

| 状态码 | 描述                  |
| --- | ------------------- |
| 200 | 请求成功。               |
| 201 | 资源创建成功。             |
| 204 | 请求成功，无内容。           |
| 400 | 请检查参数是否正确。          |
| 401 | 缺少 API 密钥或需要认证。     |
| 403 | API 密钥无效或权限不足。      |
| 404 | 未找到资源。              |
| 409 | 冲突 - 资源重复或约束违规。     |
| 429 | 超出速率限制。             |
| 500 | 内部服务器错误。            |
| 501 | 未实现。                |
| 5xx | 表示 Legitmark 服务器错误。 |

请查看错误码以获取所有可能 API 错误的完整分类。

## 错误响应格式

所有错误响应遵循此结构：

```json theme={null}
{
  "success": false,
  "error": {
    "code": 400,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "用户友好的错误消息",
    "details": [
      {
        "code": "validation/missing-field",
        "message": "field_name 为必填项。"
      }
    ]
  }
}
```

## 错误类别

### 验证错误 (400)

当请求参数不满足要求时发生验证错误：

```json theme={null}
{
  "success": false,
  "error": {
    "code": 400,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "请求参数无效。",
    "details": [
      {
        "code": "validation/missing-user_id",
        "message": "user_id 为必填项。"
      },
      {
        "code": "validation/invalid-email",
        "message": "邮箱地址格式无效。"
      }
    ]
  }
}
```

### 认证错误 (401)

当缺少或无效 API 密钥时发生认证错误：

```json theme={null}
{
  "success": false,
  "error": {
    "code": 401,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "需要认证",
    "details": "authorization/missing_token"
  }
}
```

### 授权错误 (403)

当 API 密钥缺少所需权限时发生授权错误：

```json theme={null}
{
  "success": false,
  "error": {
    "code": 403,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "权限不足",
    "details": "authorization/insufficient_permissions"
  }
}
```

### 未找到错误 (404)

当请求的资源不存在时发生未找到错误：

```json theme={null}
{
  "success": false,
  "error": {
    "code": 404,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "未找到资源",
    "details": "error/resource_not_found"
  }
}
```

### 冲突错误 (409)

当创建重复资源或违反约束时发生冲突错误：

```json theme={null}
{
  "success": false,
  "error": {
    "code": 409,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "资源已存在",
    "details": "error/duplicate_resource"
  }
}
```

### 服务器错误 (5xx)

服务器错误表示 Legitmark 基础设施问题：

```json theme={null}
{
  "success": false,
  "error": {
    "code": 500,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "内部服务器错误",
    "details": "error/internal_server_error"
  }
}
```

## 故障排除

### 常见问题

**400 错误请求**

* 检查是否包含所有必需参数
* 验证参数类型和格式
* 确保 JSON 格式正确
* 检查字段命名是否使用 snake\_case

**401 未授权**

* 验证 Authorization 标头中是否包含 API 密钥
* 检查 API 密钥格式：`Bearer leo_xxxxxxxxx`
* 确保 API 密钥有效且未过期

**403 禁止访问**

* 验证 API 密钥是否具有所需权限
* 检查资源访问是否受限
* 如有权限问题请联系支持

**404 未找到**

* 验证资源 ID/UUID 是否正确
* 检查资源是否存在
* 确保端点 URL 正确

**429 速率限制**

* 等待后重试（检查 retry-after 标头）
* 实施指数退避
* 考虑升级速率限制

**500 服务器错误**

* 短暂延迟后重试请求
* 检查 Legitmark 状态页面
* 如问题持续请联系支持

### 调试技巧

1. **检查响应标头**
   * Content-Type 应为 `application/json`
   * 速率限制标头显示当前使用情况
   * 请求 ID 用于支持查询

2. **验证请求格式**
   * 使用正确的 Content-Type 标头
   * 确保 JSON 语法有效
   * 验证所有必填字段是否包含

3. **使用最小数据测试**
   * 从最简单的请求开始
   * 逐步增加复杂性
   * 使用 API 游乐场进行测试

4. **监控速率限制**
   * 跟踪 API 使用模式
   * 实施正确的重试逻辑
   * 适当时缓存响应