​
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

Resource Errors

Validation Errors

Rate Limiting & Server Errors

​
Payment-Specific Errors

​
Transfer-Specific Errors

​
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.');
  }
}