Square API: 创建Checkout API错误解析

基础概念

Square API是Square公司提供的一组应用程序接口，允许开发者将Square的支付处理、库存管理和其他商业功能集成到自己的应用程序中。Checkout API是Square支付API的一部分，用于创建一次性支付链接或嵌入式支付表单。

常见错误类型及原因

1. 认证错误 (401 Unauthorized)

原因: 无效或过期的访问令牌，或缺少必要的权限
解决方案:
- 检查并更新你的Square访问令牌
- 确保你的应用有正确的权限范围

2. 参数验证错误 (400 Bad Request)

常见原因:
- 必填字段缺失
- 金额格式不正确
- 货币代码无效
- 过期时间设置不合理
- 重定向URL格式不正确
解决方案:
- 验证所有必填字段是否提供
- 确保金额是以货币的最小单位表示(如美元使用美分)
- 使用有效的ISO货币代码

3. 速率限制错误 (429 Too Many Requests)

原因: 超过API调用速率限制
解决方案:
- 实现指数退避重试机制
- 优化应用以减少不必要的API调用

4. 服务器错误 (5xx)

原因: Square服务器端问题
解决方案:
- 等待一段时间后重试
- 检查Square API状态页面是否有已知中断

调试建议

检查API响应:

{
  "errors": [
    {
      "category": "AUTHENTICATION_ERROR",
      "code": "UNAUTHORIZED",
      "detail": "Unauthorized"
    }
  ]
}

验证请求示例:

// 正确的Checkout API请求示例
const requestBody = {
  idempotency_key: 'unique_key_123',
  order: {
    location_id: 'YOUR_LOCATION_ID',
    line_items: [
      {
        name: 'Item Name',
        quantity: '1',
        base_price_money: {
          amount: 1000, // $10.00
          currency: 'USD'
        }
      }
    ]
  },
  ask_for_shipping_address: false,
  redirect_url: 'https://yourwebsite.com/order-confirm'
};