Guides
Troubleshooting

Troubleshooting Guide

Learn how to diagnose and resolve common issues with the PayVanta API.

Overview

This guide helps you:

  • Identify common problems
  • Understand error messages
  • Implement solutions
  • Prevent future issues

Common Issues

1. Authentication Errors

Invalid API Key

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}

Solution:

  • Verify API key format
  • Check key expiration
  • Ensure correct environment
  • Rotate if compromised

Token Expired

{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "The authentication token has expired"
  }
}

Solution:

async function handleTokenExpiry() {
  try {
    const newToken = await api.auth.refreshToken();
    return newToken;
  } catch (error) {
    // Handle refresh failure
    throw new Error("Failed to refresh token");
  }
}

2. Rate Limiting

Too Many Requests

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests"
  }
}

Solution:

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

3. Validation Errors

Invalid Input

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

Solution:

  • Validate input before sending
  • Check data types
  • Verify required fields
  • Follow format guidelines

Debugging Tools

1. Request Logging

function logRequest(request) {
  console.log({
    timestamp: new Date().toISOString(),
    method: request.method,
    path: request.path,
    headers: request.headers,
    body: request.body
  });
}

2. Response Logging

function logResponse(response) {
  console.log({
    timestamp: new Date().toISOString(),
    status: response.status,
    headers: response.headers,
    body: response.body
  });
}

3. Error Tracking

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

Common Scenarios

1. Payout Issues

Failed Payout

{
  "error": {
    "code": "PAYOUT_FAILED",
    "message": "Payout failed",
    "details": {
      "reason": "Insufficient balance"
    }
  }
}

Solution:

  • Check wallet balance
  • Verify account details
  • Ensure sufficient funds
  • Contact support if needed

2. Webhook Issues

Failed Delivery

{
  "error": {
    "code": "WEBHOOK_DELIVERY_FAILED",
    "message": "Failed to deliver webhook"
  }
}

Solution:

  • Verify webhook URL
  • Check server status
  • Monitor response times
  • Implement retry logic

3. Integration Issues

API Connection

{
  "error": {
    "code": "CONNECTION_ERROR",
    "message": "Failed to connect to API"
  }
}

Solution:

  • Check network connection
  • Verify API endpoint
  • Ensure proper authentication
  • Monitor API status

Best Practices

  1. Error Prevention

    • Validate input data
    • Implement retry logic
    • Monitor system health
    • Regular testing
  2. Debugging

    • Use logging
    • Track errors
    • Monitor performance
    • Document issues
  3. Resolution

    • Follow error guides
    • Check documentation
    • Contact support
    • Update systems

Support Resources

1. Documentation

  • API Reference
  • Integration Guides
  • Best Practices
  • Examples

2. Support Channels

  • Email support
  • Developer portal
  • Community forums
  • Status page

3. Tools

  • API Explorer
  • Webhook Tester
  • Log Viewer
  • Monitoring Dashboard

Next Steps