Error Handling

Proper error handling is essential for building robust applications with Notch Pay. This guide explains the key concepts of error handling and best practices for implementing it in your applications.

For detailed error codes, examples, and troubleshooting tips, see the API Errors Reference.

Understanding API Errors

When an error occurs, the Notch Pay API returns:

An appropriate HTTP status code
A JSON response with details about what went wrong

{
  "code": 400,
  "status": "Bad Request",
  "message": "Error message describing what went wrong",
  "errors": {
    "field_name": ["Error description for this field"]
  }
}

Common Error Categories

Authentication Errors

Status Codes: 401, 403Occur when there’s an issue with your API keys or permissions.Common causes:

Missing API key
Invalid API key
Insufficient permissions
Missing required headers

Validation Errors

Status Codes: 400, 422Occur when the request data doesn’t meet the required format or constraints.Common causes:

Missing required fields
Invalid field formats
Values outside allowed ranges
Incompatible parameter combinations

Resource Errors

Status Codes: 404, 409Occur when the requested resource doesn’t exist or there’s a conflict.Common causes:

Resource not found
Resource already exists
Resource in incompatible state

System Errors

Status Codes: 429, 500, 503Occur due to rate limiting or server-side issues.Common causes:

Rate limit exceeded
Server error
Service unavailable

Best Practices for Error Handling

Always Check for Errors

Don’t assume API requests will always succeed. Check for errors in all API responses.

// Example in JavaScript
if (!response.ok) {
  const error = await response.json();
  // Handle error
  console.error(`Error: ${error.message}`);
}

Handle Different Error Types

Implement specific handling for different types of errors.

// Example in JavaScript
if (error.code === 401) {
  // Handle authentication errors
  redirectToLogin();
} else if (error.code === 422) {
  // Handle validation errors
  showValidationErrors(error.errors);
} else if (error.code === 429) {
  // Handle rate limiting
  retryWithBackoff(request);
}

Implement Retry Logic

For transient errors like rate limiting or temporary server issues, implement retry logic with exponential backoff.

// Simplified example
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, wait and retry
        const retryAfter = Math.pow(2, retries);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        retries++;
        continue;
      }
      
      return await response.json();
    } catch (error) {
      if (retries === maxRetries - 1 || error.code < 500) {
        throw error; // Don't retry client errors or if max retries reached
      }
      
      const delay = Math.pow(2, retries);
      await new Promise(resolve => setTimeout(resolve, delay * 1000));
      retries++;
    }
  }
}

Provide User-Friendly Messages

Translate technical error messages into user-friendly messages that help users understand what went wrong and how to fix it.

// Map API errors to user-friendly messages
const errorMessages = {
  'insufficient_funds': 'Your card has insufficient funds. Please use a different card.',
};

// Display appropriate message
const userMessage = errorMessages[error.message] || 'An error occurred. Please try again.';

Logging and Monitoring

Always log errors for debugging and monitoring purposes, but be careful not to log sensitive information like card details or API keys.

Implement a robust logging system that captures:

Error codes and messages
Request IDs for correlation
Timestamps
Contextual information (without sensitive data)

Regularly review your error logs to identify patterns and improve your integration.

Next Steps

API Errors Reference - Detailed error codes and troubleshooting
Authentication - Learn about authentication methods
API Response Format - Understand the structure of API responses

Get Started

Webhooks

Security

Dashboard

Understanding API Errors

Common Error Categories

Authentication Errors

Validation Errors

Resource Errors

System Errors

Best Practices for Error Handling

Logging and Monitoring

Next Steps

​Understanding API Errors

​Common Error Categories

Authentication Errors

Validation Errors

Resource Errors

System Errors

​Best Practices for Error Handling

​Logging and Monitoring

​Next Steps

Understanding API Errors

Common Error Categories

Best Practices for Error Handling

Logging and Monitoring

Next Steps