API Errors
This guide helps you understand and troubleshoot common errors you might encounter when using the Notch Pay API.
{
"code": 400,
"status": "Bad Request",
"message": "Error message",
"errors": {
"field_name": ["Error description"]
}
}
Common Error Codes
Authentication Errors
{
"code": 401,
"status": "Unauthorized",
"message": "API key is missing"
}
Authorization header of your request.{
"code": 401,
"status": "Unauthorized",
"message": "Invalid API key"
}
{
"code": 403,
"status": "Forbidden",
"message": "You don't have permission to access this resource"
}
{
"code": 403,
"status": "Forbidden",
"message": "This endpoint requires additional authentication"
}
X-Grant header for sensitive operations.Resource Errors
{
"code": 404,
"status": "Not Found",
"message": "Payment not found"
}
{
"code": 409,
"status": "Conflict",
"message": "A payment with this reference already exists"
}
Validation Errors
{
"code": 400,
"status": "Bad Request",
"message": "Invalid request parameters"
}
{
"code": 400,
"status": "Bad Request",
"message": "Invalid JSON payload"
}
422 - Unprocessable Entity
{
"code": 422,
"status": "Unprocessable Entity",
"message": "Validation failed",
"errors": {
"amount": ["Amount must be greater than 0"],
"currency": ["Currency is required"]
}
}
errors object for specific validation errors and fix them in your request.Rate Limiting & Server Errors
{
"code": 429,
"status": "Too Many Requests",
"message": "Rate limit exceeded. Try again in 30 seconds"
}
Retry-After header in the response.500 - Internal Server Error
{
"code": 500,
"status": "Internal Server Error",
"message": "An unexpected error occurred"
}
Payment-Specific Errors
{
"code": 422,
"status": "Unprocessable Entity",
"message": "Validation failed",
"errors": {
"amount": ["Amount must be at least 100"]
}
}
{
"code": 422,
"status": "Unprocessable Entity",
"message": "Validation failed",
"errors": {
"amount": ["Amount exceeds maximum allowed (10000000)"]
}
}
{
"code": 422,
"status": "Unprocessable Entity",
"message": "Validation failed",
"errors": {
"currency": ["Currency is not supported"]
}
}
Transfer-Specific Errors
{
"code": 422,
"status": "Unprocessable Entity",
"message": "Insufficient balance to complete this transfer"
}
{
"code": 422,
"status": "Unprocessable Entity",
"message": "Validation failed",
"errors": {
"beneficiary": ["Beneficiary not found"]
}
}
Beneficiary account issues
{
"code": 422,
"status": "Unprocessable Entity",
"message": "Validation failed",
"errors": {
"account_number": ["Invalid account number for this beneficiary"]
}
}
Troubleshooting Tips
Check Request Format
Ensure your request is properly formatted and includes all required parameters. Use the API reference to verify the correct format.
Verify Authentication
Make sure you’re using the correct API key and that it’s properly included in the Authorization header.
Inspect Error Messages
Pay attention to the specific error message and the errors object in the response, which often contains detailed information about what went wrong.
Check Environment
Ensure you’re using the right environment (test or live) for your needs. Test API keys won’t work in the live environment and vice versa.
Review Logs
Check your application logs for any additional information about the request that might help identify the issue.
Contact Support
If you’re still having trouble, contact Notch Pay support with:
- The full error response
- Your request details (excluding sensitive information like API keys)
- Any steps you’ve already taken to troubleshoot
Error Handling Best Practices
Implement Retry Logic
For transient errors (like network issues or rate limiting), implement retry logic with exponential backoff.async function makeRequestWithRetry(url, options, maxRetries = 3) {
let retries = 0;
while (retries < maxRetries) {
try {
const response = await fetch(url, options);
if (response.status === 429) {
// Rate limited, get retry-after header
const retryAfter = response.headers.get('Retry-After') || 1;
await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
retries++;
continue;
}
return response;
} catch (error) {
retries++;
if (retries >= maxRetries) throw error;
// Exponential backoff
await new Promise(resolve =>
setTimeout(resolve, Math.pow(2, retries) * 1000)
);
}
}
}
Graceful Error Handling
Present user-friendly error messages to your customers while logging detailed error information for debugging.try {
const response = await makePayment(paymentData);
// Handle complete payment
} catch (error) {
// Log detailed error for debugging
console.error('Payment error:', error);
// Show user-friendly message
if (error.code === 422 && error.errors?.amount) {
showUserError('Please enter a valid payment amount');
} else if (error.code === 401) {
showUserError('Authentication error. Please try again later.');
} else {
showUserError('Unable to process payment. Please try again later.');
}
}
For more detailed information about specific API endpoints and their potential errors, refer to the documentation for each endpoint.
Need more help? Contact our support team with details about the error you’re encountering. 
