错误处理 | Payve Docs

本文档描述了 Payve API 的错误响应格式和所有错误码的详细说明。正确理解和处理这些错误对于构建健壮的集成至关重要。

错误响应格式

所有 API 错误响应都遵循统一的 JSON 格式：

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "提供的 API 密钥无效或已过期",
    "details": {
      "field": "apiKey",
      "reason": "expired"
    },
    "requestId": "req_abc123xyz",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

JSON

代码已折叠

共 12 行

响应字段说明

字段	类型	说明
`code`	string	错误码，用于程序识别
`message`	string	人类可读的错误描述
`details`	object	额外的错误详情（可选）
`requestId`	string	请求 ID，用于追踪和调试
`timestamp`	string	错误发生时间（ISO 8601）

HTTP 状态码

我们使用标准的 HTTP 状态码来表示请求的结果：

状态码	含义	场景
`200`	成功	请求成功处理
`201`	已创建	资源创建成功（如新订单）
`400`	错误请求	请求参数错误或格式不正确
`401`	未授权	缺少或无效的认证凭据
`403`	禁止访问	权限不足
`404`	未找到	请求的资源不存在
`409`	冲突	资源状态冲突（如重复订单）
`429`	请求过多	触发速率限制
`500`	服务器错误	服务器内部错误
`503`	服务不可用	服务暂时不可用

错误码列表

认证相关错误（1xxx）

1001401

INVALID_API_KEY

API 密钥无效或已过期

解决方案：检查 API 密钥是否正确，确认密钥未被撤销或过期

1002401

MISSING_AUTH_HEADER

缺少认证头部

解决方案：在请求头中添加 Authorization: Bearer <token>

1003401

TOKEN_EXPIRED

JWT 令牌已过期

解决方案：重新获取新的访问令牌

1004403

INSUFFICIENT_PERMISSIONS

权限不足

解决方案：检查 API 密钥的权限设置，确保有执行该操作的权限

支付相关错误（2xxx）

2001400

INVALID_AMOUNT

支付金额无效

解决方案：确保金额为正数且不超过最大限额

2002400

AMOUNT_TOO_SMALL

支付金额低于最小限额

解决方案：查看对应币种和网络的最小金额要求，确保金额满足最小限制

2003400

UNSUPPORTED_CURRENCY

不支持的币种

解决方案：查看支持的币种列表，使用支持的币种代码

2004400

ORDER_EXPIRED

支付订单已过期

解决方案：创建新的支付订单，订单有效期为 30 分钟

2005404

ORDER_NOT_FOUND

订单不存在

解决方案：检查订单 ID 是否正确

2005409

DUPLICATE_ORDER

订单号重复

解决方案：使用唯一的商户订单号，或查询已存在的订单

2006400

PAYMENT_ALREADY_COMPLETED

订单已完成支付

解决方案：查询订单状态，避免重复支付

钱包相关错误（3xxx）

3001400

INSUFFICIENT_BALANCE

余额不足

解决方案：检查账户余额，确保有足够的资金进行提现

3002400

INVALID_ADDRESS

钱包地址无效

解决方案：检查地址格式是否正确，确保地址与币种网络匹配

3003400

WITHDRAWAL_LIMIT_EXCEEDED

超出提现限额

解决方案：降低提现金额或联系客服提高限额

3004403

ADDRESS_NOT_WHITELISTED

地址不在白名单中

解决方案：在商户后台添加提现地址到白名单

系统相关错误（4xxx）

4001429

RATE_LIMIT_EXCEEDED

请求频率超限

解决方案：降低请求频率，查看响应头中的 X-RateLimit-* 了解限制详情

4002503

SERVICE_UNAVAILABLE

服务暂时不可用

解决方案：稍后重试，查看状态页面了解服务状态

4003500

INTERNAL_ERROR

内部服务器错误

解决方案：联系技术支持，提供请求 ID 以便追踪问题

错误处理最佳实践

1. 实现重试机制

对于临时性错误（如网络问题），实现指数退避重试：

async function requestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === '4002' && i < maxRetries - 1) {
        // 服务不可用，等待后重试
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

JAVASCRIPT

代码已折叠

共 14 行

2. 记录错误信息

始终记录完整的错误响应，包括请求 ID：

catch (error) {
  console.error('API Error:', {
    code: error.code,
    message: error.message,
    requestId: error.requestId,
    timestamp: error.timestamp
  });
}

3. 用户友好的错误提示

将技术错误转换为用户可理解的提示：

function getUserMessage(errorCode) {
  const messages = {
    '2001': '支付金额格式不正确，请重新输入',
    '2003': '订单已过期，请重新下单',
    '3001': '余额不足，请充值后再试',
    // ...
  };
  return messages[errorCode] || '操作失败，请稍后重试';
}

4. 监控错误趋势

跟踪错误发生频率，及时发现系统问题：

设置错误率告警
分析错误模式
定期审查错误日志

联系支持

如果您遇到未列出的错误码或需要技术协助：

技术支持

邮箱：support@payve.io

在线客服：工作日 9:00-18:00

提交工单：merchant.payve.io/support

请提供请求 ID、错误码和相关日志以加快问题解决。