Skip to main content

​
API Errors

This guide helps you understand and troubleshoot common errors you might encounter when using the Notch Pay API.

​
Error Response Format

{
  "code": 400,
  "status": "Bad Request",
  "message": "Error message",
  "errors": {
    "field_name": ["Error description"]
  }
}

​
Common Error Codes

Authentication Errors

​
API key missing
error
{
  "code": 401,
  "status": "Unauthorized",
  "message": "API key is missing"
}
Solution: Include your API key in the Authorization header of your request.
​
Invalid API key
error
{
  "code": 401,
  "status": "Unauthorized",
  "message": "Invalid API key"
}
Solution: Check that you’re using the correct API key. Make sure you’re not mixing test and live keys.
​
Insufficient permissions
error
{
  "code": 403,
  "status": "Forbidden",
  "message": "You don't have permission to access this resource"
}
Solution: Verify that your API key has the necessary permissions for the operation you’re trying to perform.
​
Missing grant key
error
{
  "code": 403,
  "status": "Forbidden",
  "message": "This endpoint requires additional authentication"
}
Solution: Include your private key in the X-Grant header for sensitive operations.

Resource Errors

​
Resource not found
error
{
  "code": 404,
  "status": "Not Found",
  "message": "Payment not found"
}
Solution: Check that the ID or reference you’re using exists and belongs to your account.
​
Duplicate resource
error
{
  "code": 409,
  "status": "Conflict",
  "message": "A payment with this reference already exists"
}
Solution: Use a unique reference for each payment or other resource you create.

Validation Errors

​
Invalid request
error
{
  "code": 400,
  "status": "Bad Request",
  "message": "Invalid request parameters"
}
Solution: Check your request parameters and make sure they match the API documentation.
​
Invalid JSON
error
{
  "code": 400,
  "status": "Bad Request",
  "message": "Invalid JSON payload"
}
Solution: Ensure your request body contains valid JSON.
​
Validation failed
error
{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": {
    "amount": ["Amount must be greater than 0"],
    "currency": ["Currency is required"]
  }
}
Solution: Check the errors object for specific validation errors and fix them in your request.

Rate Limiting & Server Errors

​
Rate limit exceeded
error
{
  "code": 429,
  "status": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 30 seconds"
}
Solution: Implement exponential backoff and respect the Retry-After header in the response.
​
Server error
error
{
  "code": 500,
  "status": "Internal Server Error",
  "message": "An unexpected error occurred"
}
Solution: This is a server-side error. If it persists, contact Notch Pay support with details about your request.

​
Payment-Specific Errors

  • Payment Creation
  • Payment Processing
​
Amount too small
error
{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": {
    "amount": ["Amount must be at least 100"]
  }
}
Solution: Ensure the payment amount meets the minimum requirement for the selected currency.
​
Amount too large
error
{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": {
    "amount": ["Amount exceeds maximum allowed (10000000)"]
  }
}
Solution: Break down large payments into smaller transactions or contact support to increase your limit.
​
Unsupported currency
error
{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": {
    "currency": ["Currency is not supported"]
  }
}
Solution: Use one of the supported currencies.
​
Missing customer info
error
{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": {
    "customer": ["Customer information is required"]
  }
}
Solution: Provide at least an email or phone number for the customer.
​
Invalid email
error
{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": {
    "customer.email": ["Invalid email address"]
  }
}
Solution: Provide a valid email address for the customer.

​
Transfer-Specific Errors

​
Insufficient funds
error
{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Insufficient balance to complete this transfer"
}
Solution: Add funds to your Notch Pay account before attempting the transfer.
​
Invalid beneficiary
error
{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": {
    "beneficiary": ["Beneficiary not found"]
  }
}
Solution: Ensure the beneficiary exists and is correctly specified.
​
Beneficiary account issues
error
{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": {
    "account_number": ["Invalid account number for this beneficiary"]
  }
}
Solution: Verify the beneficiary’s account information.

​
Troubleshooting Tips

1

Check Request Format

Ensure your request is properly formatted and includes all required parameters. Use the API reference to verify the correct format.
2

Verify Authentication

Make sure you’re using the correct API key and that it’s properly included in the Authorization header.
3

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.
4

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.
5

Review Logs

Check your application logs for any additional information about the request that might help identify the issue.
6

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.
⌘I