跳转到主要内容

​
响应码

Legitmark 使用标准 HTTP 状态码来指示请求的成功或失败。 一般来说，2xx HTTP 状态码表示成功，4xx 状态码表示用户相关错误，5xx 状态码表示基础设施问题。
状态码描述
200请求成功。
201资源创建成功。
204请求成功，无内容。
400请检查参数是否正确。
401缺少 API 密钥或需要认证。
403API 密钥无效或权限不足。
404未找到资源。
409冲突 - 资源重复或约束违规。
429超出速率限制。
500内部服务器错误。
501未实现。
5xx表示 Legitmark 服务器错误。
请查看错误码以获取所有可能 API 错误的完整分类。

​
错误响应格式

所有错误响应遵循此结构： 
{
  "success": false,
  "error": {
    "code": 400,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "用户友好的错误消息",
    "details": [
      {
        "code": "validation/missing-field",
        "message": "field_name 为必填项。"
      }
    ]
  }
}

​
错误类别

​
验证错误 (400)

当请求参数不满足要求时发生验证错误： 
{
  "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 密钥时发生认证错误： 
{
  "success": false,
  "error": {
    "code": 401,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "需要认证",
    "details": "authorization/missing_token"
  }
}

​
授权错误 (403)

当 API 密钥缺少所需权限时发生授权错误： 
{
  "success": false,
  "error": {
    "code": 403,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "权限不足",
    "details": "authorization/insufficient_permissions"
  }
}

​
未找到错误 (404)

当请求的资源不存在时发生未找到错误： 
{
  "success": false,
  "error": {
    "code": 404,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "未找到资源",
    "details": "error/resource_not_found"
  }
}

​
冲突错误 (409)

当创建重复资源或违反约束时发生冲突错误： 
{
  "success": false,
  "error": {
    "code": 409,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "资源已存在",
    "details": "error/duplicate_resource"
  }
}

​
服务器错误 (5xx)

服务器错误表示 Legitmark 基础设施问题： 
{
  "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 使用模式
    • 实施正确的重试逻辑
    • 适当时缓存响应