跳转至

错误码参考☍

本文档提供了API调用过程中可能遇到的常见错误码、错误信息以及相应的解决方案。

错误码格式☍

所有API错误响应都遵循以下JSON格式：

{
  "code": "错误码",
  "message": "错误信息描述",
  "requestId": "请求ID"
}
  • code: 唯一标识错误类型的代码
  • message: 对错误的详细描述
  • requestId: 用于追踪和调试的唯一请求标识符

通用错误码☍

错误码 错误信息 描述 解决方案
InvalidParameter 参数无效 提供的参数格式不正确或缺少必要参数 检查API文档，确保所有必需参数都已提供且格式正确
MissingParameter 缺少必要参数 请求中缺少必需的参数 参考API文档，添加所有必需的参数
InvalidRequest 无效的请求 请求格式不正确或包含无效数据 检查请求格式和内容是否符合API要求
Unauthorized 未授权 用户未经授权或授权已过期 检查认证凭据是否有效，可能需要重新获取访问令牌
Forbidden 禁止访问 用户无权执行请求的操作 确认用户拥有执行该操作的权限
ResourceNotFound 资源不存在 请求的资源不存在 检查资源ID或路径是否正确
ResourceAlreadyExists 资源已存在 尝试创建的资源已经存在 使用不同的标识符或检查是否应该更新现有资源
RateLimitExceeded 超出请求限制 超过了API调用频率限制 减少API调用频率或联系支持团队增加限制
InternalError 内部服务错误 服务器内部错误 稍后重试，如果问题持续存在，请联系支持团队
ServiceUnavailable 服务不可用 服务暂时不可用 稍后重试，检查服务状态页面获取更多信息

认证与授权错误☍

错误码 错误信息 描述 解决方案
InvalidCredentials 无效的凭据 提供的认证凭据无效 检查用户名/密码或访问令牌是否正确
TokenExpired 令牌已过期 访问令牌已过期 使用刷新令牌获取新的访问令牌
InvalidToken 无效的令牌 提供的令牌格式不正确或已被撤销 重新获取有效的访问令牌
InsufficientPermissions 权限不足 用户没有执行请求操作的权限 请求更高级别的权限或使用具有适当权限的账户

用户相关错误☍

错误码 错误信息 描述 解决方案
UserNotFound 用户不存在 指定的用户不存在 检查用户ID或用户名是否正确
UserAlreadyExists 用户已存在 尝试创建的用户已存在 使用不同的用户名或邮箱
InvalidPassword 密码无效 提供的密码不符合安全要求 使用符合密码策略的密码（通常需要包含大小写字母、数字和特殊字符）
AccountLocked 账户已锁定 由于多次登录失败，账户已被锁定 等待锁定期过后再尝试，或联系管理员解锁账户
EmailNotVerified 邮箱未验证 用户邮箱尚未验证 完成邮箱验证流程

应用相关错误☍

错误码 错误信息 描述 解决方案
AppNotFound 应用不存在 指定的应用不存在 检查应用ID是否正确
AppDisabled 应用已禁用 应用已被管理员禁用 联系管理员启用应用
AppQuotaExceeded 应用配额超出限制 应用已达到资源使用限制 升级应用计划或减少资源使用
InvalidAppConfiguration 应用配置无效 应用配置参数无效 检查应用配置参数是否符合要求

数据存储错误☍

错误码 错误信息 描述 解决方案
TableNotFound 表不存在 指定的数据表不存在 检查表名是否正确，或先创建表
InvalidQuery 查询无效 提供的查询语法或参数无效 检查查询语法和参数是否符合要求
DataValidationFailed 数据验证失败 提交的数据不符合验证规则 根据字段验证规则修改数据
TransactionFailed 事务失败 数据库事务执行失败 检查事务中的操作是否都有效，可能需要分解复杂事务

文件操作错误☍

错误码 错误信息 描述 解决方案
FileNotFound 文件不存在 指定的文件不存在 检查文件路径或ID是否正确
FileSizeTooLarge 文件大小超出限制 上传的文件超过大小限制 减小文件大小或分块上传
InvalidFileType 文件类型无效 不支持上传的文件类型 使用支持的文件类型
StorageQuotaExceeded 存储配额超出限制 已达到存储空间限制 删除不需要的文件或升级存储计划

支付相关错误☍

错误码 错误信息 描述 解决方案
PaymentFailed 支付失败 支付处理失败 检查支付信息是否正确，或尝试其他支付方式
InsufficientFunds 资金不足 账户余额不足以完成交易 充值账户或使用其他支付方式
PaymentMethodNotSupported 支付方式不支持 所选支付方式不可用 选择其他支持的支付方式
OrderNotFound 订单不存在 指定的订单不存在 检查订单ID是否正确
OrderAlreadyPaid 订单已支付 尝试支付已完成支付的订单 无需再次支付，检查订单状态

第三方集成错误☍

错误码 错误信息 描述 解决方案
ThirdPartyServiceError 第三方服务错误 调用第三方服务时发生错误 检查第三方服务状态，稍后重试
InvalidOAuthToken OAuth令牌无效 提供的OAuth令牌无效或已过期 重新进行OAuth授权流程
WebhookVerificationFailed Webhook验证失败 Webhook签名验证失败 检查Webhook密钥和签名算法是否正确

如何处理错误☍

  1. 检查错误码和消息：首先识别返回的错误码和消息，了解问题的性质。

  2. 参考文档：根据错误码查阅本文档，了解可能的原因和解决方案。

  3. 检查请求：确保请求格式正确，所有必需参数都已提供且格式正确。

  4. 查看日志：检查应用日志以获取更详细的错误信息。

  5. 使用requestId：在联系支持团队时提供requestId，以便更快地定位问题。

  6. 实现重试机制：对于临时性错误（如服务不可用），实现带有退避策略的重试机制。

  7. 错误处理最佳实践：

  8. 始终检查API响应的状态码
  9. 实现适当的错误处理逻辑
  10. 向用户显示友好的错误消息
  11. 记录详细的错误信息以便调试

如果您遇到未在本文档中列出的错误码，或需要更多帮助，请联系我们的支持团队。

评论