Guides
Error Handling

Error Handling

Learn how to handle errors and exceptions in the PayVanta API.

Overview

Proper error handling is crucial for:

  • Maintaining application stability
  • Providing good user experience
  • Debugging issues
  • Monitoring system health

Error Response Format

Standard Format

{
  "success": false,
  "message": "ERROR_CODE",
  "error": "Human readable error message"
}

HTTP Status Codes

  • 200: Success
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 429: Too Many Requests
  • 500: Internal Server Error

Common Error Types

Authentication Errors

{
  "success": false,
  "message": "INVALID_TOKEN",
  "error": "Invalid or expired token"
}

Validation Errors

{
  "success": false,
  "message": "VALIDATION_ERROR",
  "error": "Invalid input data",
    "details": {
      "amount": "Must be greater than 0"
  }
}

Business Logic Errors

{
  "success": false,
  "message": "INSUFFICIENT_BALANCE",
  "error": "Insufficient wallet balance"
}

Error Handling Best Practices

1. Proper Error Catching

try {
  const response = await api.payout.create({
    order_id: "010049920200145054",
    amount: "99",
    account_number: "390000000003",
    ifsc: "SBIN0017886",
    beneficiaryName: "Jason Stathom",
    mobile_no: "xxxxxxxxxxx"
  });
} catch (error) {
  if (error.message === "INSUFFICIENT_BALANCE") {
    // Handle insufficient balance
  } else if (error.message === "INVALID_ACCOUNT") {
    // Handle invalid account
  } else {
    // Handle other errors
  }
}

2. Retry Logic

async function withRetry(operation, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation();
    } catch (error) {
      if (error.code === "RATE_LIMIT" && i < maxRetries - 1) {
        await sleep(1000 * Math.pow(2, i));
        continue;
      }
      throw error;
    }
  }
}

3. Error Logging

function logError(error, context) {
  console.error({
    timestamp: new Date().toISOString(),
    error: {
      code: error.code,
      message: error.message,
      details: error.details
    },
    context: context
  });
}

Rate Limiting

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1616248800

Handling Rate Limits

async function handleRateLimit(error) {
  if (error.code === "RATE_LIMIT") {
    const resetTime = error.headers["X-RateLimit-Reset"];
    const waitTime = resetTime - Date.now() / 1000;
    await sleep(waitTime * 1000);
    return retryOperation();
  }
}

Error Monitoring

1. Track Error Rates

  • Monitor error frequency
  • Set up alerts
  • Track error patterns

2. Error Categories

  • Authentication errors
  • Validation errors
  • Business logic errors
  • System errors

3. Debugging Information

  • Request ID
  • Timestamp
  • User context
  • Stack trace

Best Practices

  1. Error Prevention

    • Validate input data
    • Check preconditions
    • Handle edge cases
    • Use type checking
  2. Error Recovery

    • Implement retry logic
    • Use fallback options
    • Maintain state consistency
    • Handle partial failures
  3. User Communication

    • Clear error messages
    • Actionable feedback
    • Recovery instructions
    • Support contact

Next Steps