错误处理

StablePay API 使用标准的 HTTP 状态码和结构化的错误响应来指示请求结果。

HTTP 状态码

状态码	说明
200	请求成功
201	资源创建成功
400	请求参数错误
401	认证失败
403	权限不足
404	资源不存在
429	请求频率超限
500	服务器内部错误

Status Code	Description
200	Request successful
201	Resource created
400	Bad request parameters
401	Authentication failed
403	Permission denied
404	Resource not found
429	Rate limit exceeded
500	Internal server error

错误响应格式

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Required parameter 'amount' is missing",
    "param": "amount",
    "doc_url": "https://docs.stablepay.co/api/errors#parameter_missing"
  }
}

常见错误类型

错误类型	说明
`authentication_error`	认证相关错误
`invalid_request_error`	请求参数错误
`permission_error`	权限不足
`rate_limit_error`	频率限制错误
`api_error`	API 内部错误

Error Type	Description
`authentication_error`	Authentication related errors
`invalid_request_error`	Invalid request parameters
`permission_error`	Permission denied
`rate_limit_error`	Rate limit exceeded
`api_error`	Internal API errors

错误处理示例

try {
  const session = await stablepay.paymentSessions.create({
    amount: { value: '10000', currency: 'USDT' }
  });
} catch (error) {
  if (error.type === 'authentication_error') {
    console.error('Authentication failed:', error.message);
  } else if (error.type === 'invalid_request_error') {
    console.error('Invalid request:', error.param, error.message);
  } else {
    console.error('API error:', error.message);
  }
}