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
-
Error Prevention
- Validate input data
- Implement retry logic
- Monitor system health
- Regular testing
-
Debugging
- Use logging
- Track errors
- Monitor performance
- Document issues
-
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