Troubleshooting
Common issues and solutions for Paycrest integration
Troubleshooting Guide
This guide helps you resolve common issues when integrating with the Paycrest API.
Common Issues
Authentication Issues
Authentication Issues
Invalid API Key
If you’re getting 401 Unauthorized errors:
- Verify your API key is correct and not expired
- Ensure you’re using the correct header:
API-Key(notX-API-Key) - Check that your account has been KYC verified
- Confirm your API key has the necessary permissions
Example Request
Order Creation Errors
Order Creation Errors
400 Bad Request
Common causes and solutions:
- Invalid amount: Amount must be a positive number
- Unsupported token: Check supported tokens in the resources section
- Invalid network: Ensure the network supports your chosen token
- Missing recipient details: All recipient fields are required
- Invalid institution: Check supported institutions for the currency
Example Error Response
Order Status Issues
Order Status Issues
Order Stuck in Pending
If your order has been in pending status for more than 10 minutes:
- Check if there are any network issues or maintenance
- Verify the recipient details are correct
- Contact support with your order ID
Order Refunded
Common reasons for a refund:
- Insufficient provider liquidity
- Recipient account issues
- Compliance or regulatory restrictions
- Network congestion or technical issues
Webhook Issues
Webhook Issues
Webhooks Not Receiving
Troubleshooting steps:
- Verify your webhook URL is publicly accessible
- Check that your server returns 200 OK responses
- Ensure your webhook endpoint can handle POST requests
- Verify webhook signature for security
Webhook Signature Verification
Network Issues
Network Issues
Blockchain Network Problems
If you’re experiencing issues with specific networks:
- High gas fees: Consider using L2 networks like Base, Arbitrum, Polygon, Celo, or Lisk
- Slow confirmations: Some networks may have congestion
- Network maintenance: Check our Telegram community for updates
Supported Networks
Ethereum L2s
- Base
- Arbitrum One
- Polygon
- Celo
- Lisk
Other Networks
- BNB Smart Chain
- Tron
Error Codes Reference
4xx Client Errors
- 400: Bad Request - Invalid parameters
- 401: Unauthorized - Invalid API key
- 403: Forbidden - Insufficient permissions
- 404: Not Found - Resource doesn’t exist
- 429: Too Many Requests - Rate limit exceeded
5xx Server Errors
- 500: Internal Server Error
- 502: Bad Gateway
- 503: Service Unavailable
- 504: Gateway Timeout
Rate Limits
Paycrest implements rate limiting to ensure fair usage. Limits vary by endpoint and account tier.
Unauthenticated
- 20 requests/second
- Applies to requests without a valid API key
Authenticated
- 500 requests/second
- Applies to requests with a valid API key
Testing & Debugging
Enable Debug Logging
Add debug headers to see detailed request/response information:
Check API Status
Monitor API status and performance:
- Monitor response times and error rates
- Set up alerts for critical endpoints
- Join our Telegram community for real-time updates
Contact Support
If you’re still experiencing issues:
- Email: [email protected]
- Telegram: Community Chat
- Include order IDs and error details
Best Practices
Error Handling
- Always check response status codes
- Implement exponential backoff for retries
- Log errors with context for debugging
- Handle network timeouts gracefully
Security
- Store API keys securely (use environment variables)
- Verify webhook signatures
- Use HTTPS for all API calls
- Rotate API keys regularly
Performance
- Cache supported currencies and institutions
- Use webhooks instead of polling
- Implement connection pooling
- Monitor rate limits
Monitoring
- Track order success/failure rates
- Monitor response times
- Set up alerts for critical failures
- Log important events for audit trails
Getting Help
Documentation
Browse our comprehensive API documentation with interactive examples
Community
Join our Telegram community for peer support and discussions
Support Team
Contact our technical support team for personalized assistance
GitHub Issues
Report bugs and request features through our GitHub repository
This troubleshooting guide covers the most common issues. For specific problems not covered here, please contact our support team with detailed information about your use case and any error messages you’re seeing.