API错误返回规范有哪些

发布时间：2021-11-16 16:55:07 作者：iii
来源：亿速云阅读：270

# API错误返回规范有哪些

## 目录
1. [引言](#引言)
2. [错误返回的基本结构](#错误返回的基本结构)
3. [HTTP状态码规范](#http状态码规范)
4. [错误码设计原则](#错误码设计原则)
5. [错误信息格式](#错误信息格式)
6. [常见错误分类](#常见错误分类)
7. [国际化与本地化](#国际化与本地化)
8. [安全注意事项](#安全注意事项)
9. [最佳实践案例](#最佳实践案例)
10. [总结](#总结)

---

## 引言
在API开发中，规范的错误返回机制是保证系统可维护性和用户体验的关键要素。据统计，超过40%的API相关问题源于不规范的错误处理。本文将深入探讨API错误返回的完整规范体系。

（此处可扩展引入行业背景数据或案例）

---

## 错误返回的基本结构
标准的错误响应应包含以下核心字段：

```json
{
  "code": "INVALID_PARAMETER",
  "message": "Invalid email format",
  "details": {
    "field": "email",
    "requirement": "RFC 5322 format"
  },
  "trace_id": "a1b2c3d4-5678-90ef"
}

必要字段说明

字段名	类型	必填	说明
code	string	是	业务错误码
message	string	是	人类可读的错误描述
details	object	否	调试用详细信息
trace_id	string	推荐	请求追踪ID（用于日志关联）

HTTP状态码规范

应严格遵循RFC 7231标准：

主要状态码分类

状态码	类别	典型场景
400	Bad Request	参数校验失败
401	Unauthorized	未提供有效凭证
403	Forbidden	权限不足
404	Not Found	资源不存在
429	Too Many Requests	限流触发
500	Server Error	未处理的服务器异常
503	Service Unavailable	服务不可用

使用建议

不要滥用200状态码返回错误
5xx错误应包含可选的retry_after字段
保持状态码与业务错误码的语义一致

错误码设计原则

命名规范

采用大写下划线格式（例：RATE_LIMIT_EXCEEDED）
前缀区分模块（例：AUTH_/PAYMENT_）

分级体系

建议采用三级分类：

<服务标识>_<模块>_<具体错误>
└── USER_SERVICE
    ├── AUTH_INVALID_TOKEN
    └── PROFILE_EML_EXISTS

保留码范围

范围	用途
000-099	系统级错误
100-199	认证授权错误
200-299	业务校验错误

错误信息格式

消息内容要求

避免暴露敏感信息（如SQL错误）
包含可操作建议（例：”请检查邮箱格式”）
技术细节放入details字段

多语言支持

{
  "message": {
    "en": "Invalid parameter",
    "zh-CN": "参数无效"
  }
}

常见错误分类

输入验证错误

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    {
      "field": "age",
      "error": "Must be positive integer"
    }
  ]
}

业务逻辑错误

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Account balance不足",
  "required_amount": 100.00,
  "current_balance": 80.00
}

系统错误

{
  "code": "DATABASE_TIMEOUT",
  "message": "系统繁忙，请稍后重试",
  "retryable": true,
  "retry_after": 30
}

国际化与本地化

实现方案

通过Accept-Language头识别语言
错误码与消息分离存储
动态加载消息模板

示例结构

errors:
  AUTH_FLED:
    en: "Authentication failed"
    zh: "认证失败"
    ja: "認証に失敗しました"

安全注意事项

信息泄露防护
- 禁止返回堆栈跟踪
- 数据库错误需脱敏处理

限流信息暴露

// 不建议
{
 "remaining": 0,
 "reset_time": "2023-01-01T00:00:00Z"
}

错误分类策略
- 客户端错误（4xx）可显示详细信息
- 服务端错误（5xx）应模糊处理

最佳实践案例

GitHub API

{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "Issue",
      "field": "title",
      "code": "missing_field"
    }
  ],
  "documentation_url": "https://docs.github.com/rest/reference/issues#create-an-issue"
}

Stripe API

{
  "error": {
    "type": "card_error",
    "code": "expired_card",
    "doc_url": "https://stripe.com/docs/error-codes/expired-card"
  }
}

总结

完整的错误返回规范应包含： 1. 标准的HTTP状态码 2. 结构化的错误体 3. 明确的错误分类 4. 完善的安全控制 5. 可扩展的国际化方案

“好的错误处理不是事后补救，而是事先设计” —— Martin Fowler

（此处可加入参考文献和扩展阅读链接） “`

注：实际使用时可根据需要： 1. 补充具体行业的案例 2. 增加各字段的详细示例 3. 插入架构图或状态转换图 4. 添加团队内部的特殊规范要求