跳到主要内容

错误处理

在 Pelago 集成中优雅地处理错误。

错误响应格式​

所有 API 错误遵循一致的格式：

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "The 'amount' parameter is required",
    "param": "amount",
    "doc_url": "https://docs.pelago.tech/errors#missing_parameter"
  }
}

HTTP 状态码​

状态码描述处理方式
200成功处理响应
201已创建资源已创建
400请求错误修正请求参数
401未授权检查 API 密钥
403无权限检查权限
404未找到检查资源 ID
409冲突处理幂等性
422无法处理修正验证错误
429请求过多降低请求频率
500服务器错误重试（指数退避）
503服务不可用稍后重试

错误类型​

authentication_error​

无效或缺失的 API 凭证。

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided"
  }
}

解决方案：

// 检查 API 密钥格式
if (!apiKey.startsWith('pk_')) {
  throw new Error('Invalid API key format');
}

// 验证密钥已配置
if (!process.env.PELAGO_API_KEY) {
  throw new Error('PELAGO_API_KEY not configured');
}

invalid_request_error​

请求参数无效或缺失。

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_amount",
    "message": "Amount must be greater than 0",
    "param": "amount"
  }
}

常见错误码：

错误码描述
missing_parameter缺少必填字段
invalid_parameter字段值无效
invalid_amount金额 \<= 0 或过大
invalid_currency不支持的币种
invalid_network不支持的网络
invalid_wallet钱包地址格式错误

rate_limit_error​

请求过于频繁。

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 60 seconds"
  }
}

解决方案：

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.type === 'rate_limit_error') {
        const delay = Math.pow(2, i) * 1000; // 指数退避
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

payment_error​

支付相关错误。

错误码描述恢复方式
payment_expired支付超时创建新支付
payment_already_completed已支付无需操作
insufficient_funds客户余额不足客户充值
network_error区块链问题稍后重试
wallet_error钱包无效修正钱包地址

api_error​

服务端错误。

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An internal error occurred"
  }
}

解决方案： 使用指数退避重试。

SDK 错误处理​

JavaScript​

import { PelagoClient, PelagoError } from '@pelago/sdk';

try {
  const payment = await pelago.payments.create({
    amount: 100,
    currency: 'USD',
    // ...
  });
} catch (error) {
  if (error instanceof PelagoError) {
    switch (error.type) {
      case 'authentication_error':
        console.error('请检查 API 密钥');
        break;
      case 'invalid_request_error':
        console.error('无效参数:', error.param);
        break;
      case 'rate_limit_error':
        console.error('请求过快，重试中...');
        await delay(60000);
        // 重试
        break;
      case 'payment_error':
        console.error('支付错误:', error.code);
        break;
      default:
        console.error('未知错误:', error.message);
    }
  } else {
    // 网络错误或其他问题
    console.error('连接错误:', error);
  }
}

Python​

from pelago import PelagoClient, PelagoError
from pelago.errors import (
    AuthenticationError,
    InvalidRequestError,
    RateLimitError,
    PaymentError
)

try:
    payment = pelago.payments.create(
        amount=100,
        currency='USD',
        # ...
    )
except AuthenticationError as e:
    print('请检查 API 密钥')
except InvalidRequestError as e:
    print('无效参数:', e.param)
except RateLimitError:
    print('触发速率限制，重试中...')
    time.sleep(60)
    # 重试
except PaymentError as e:
    print('支付错误:', e.code)
except PelagoError as e:
    print('未知错误:', e.message)

验证错误​

对于验证错误，检查所有失败的字段：

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Request validation failed",
    "errors": [
      {
        "param": "amount",
        "message": "Amount must be greater than 0"
      },
      {
        "param": "currency",
        "message": "Currency must be uppercase"
      }
    ]
  }
}

处理方式：

catch (error) {
  if (error.code === 'validation_failed') {
    for (const fieldError of error.errors) {
      console.error(`${fieldError.param}: ${fieldError.message}`);
    }
  }
}

网络错误处理​

async function createPaymentWithRetry(params: PaymentParams) {
  const maxRetries = 3;
  let lastError: Error;
  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await pelago.payments.create(params);
    } catch (error) {
      lastError = error;
      
      // 客户端错误不重试
      if (error.type === 'invalid_request_error') {
        throw error;
      }
      
      // 认证错误不重试
      if (error.type === 'authentication_error') {
        throw error;
      }
      
      // 服务器错误和网络问题进行重试
      if (attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`重试 ${attempt}/${maxRetries}，${delay}ms 后`);
        await new Promise(r => setTimeout(r, delay));
      }
    }
  }
  
  throw lastError;
}

错误日志最佳实践​

import { PelagoError } from '@pelago/sdk';

function logError(error: Error, context: object) {
  if (error instanceof PelagoError) {
    console.error({
      type: 'pelago_error',
      errorType: error.type,
      code: error.code,
      message: error.message,
      param: error.param,
      requestId: error.requestId, // 用于技术支持
      ...context
    });
  } else {
    console.error({
      type: 'unknown_error',
      message: error.message,
      stack: error.stack,
      ...context
    });
  }
}

// 使用示例
try {
  await pelago.payments.create(params);
} catch (error) {
  logError(error, {
    action: 'create_payment',
    orderId: params.metadata.orderId
  });
  throw error;
}

下一步​