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

401 - Unauthorized

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.

403 - Forbidden

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

404 - Not Found

409 - Conflict

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

400 - Bad Request

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.

422 - Unprocessable Entity

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

429 - Too Many Requests

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.

500 - Internal Server Error

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

Invalid Amount

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.

Currency Issues

Unsupported currency

error

{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": {
    "currency": ["Currency is not supported"]
  }
}

Solution: Use one of the supported currencies.

Customer Information

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.

Invalid Amount

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.

Currency Issues

Unsupported currency

error

{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": {
    "currency": ["Currency is not supported"]
  }
}

Solution: Use one of the supported currencies.

Customer Information

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.

Invalid Payment Status

Already processed

error

{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Payment has already been processed"
}

Solution: Check the payment status before attempting to process it again.

Canceled payment

error

{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Payment has been canceled"
}

Solution: Create a new payment instead of trying to process a canceled one.

Payment Channel Issues

Invalid channel

error

{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": {
    "channel": ["Invalid payment channel"]
  }
}

Solution: Use one of the supported payment channels.

Missing channel data

error

{
  "code": 422,
  "status": "Unprocessable Entity",
  "message": "Validation failed",
  "errors": {
    "data.phone": ["Phone number is required for mobile money payments"]
  }
}

Solution: Provide the required data for the selected payment channel.

Transfer-Specific Errors

Insufficient Balance

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.

Beneficiary Issues

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

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

Introduction

Core Resources

Additional Resources

API Specification

API Errors

API Errors

Error Response Format

Common Error Codes

Authentication Errors

Resource Errors

Validation Errors

Rate Limiting & Server Errors

Payment-Specific Errors

Transfer-Specific Errors

Troubleshooting Tips

Error Handling Best Practices

Implement Retry Logic

Graceful Error Handling

Introduction

Core Resources

Additional Resources

API Specification

​API Errors

​Error Response Format

​Common Error Codes

Authentication Errors

Resource Errors

Validation Errors

Rate Limiting & Server Errors

​Payment-Specific Errors

​Transfer-Specific Errors

​Troubleshooting Tips

​Error Handling Best Practices

Implement Retry Logic

Graceful Error Handling

API Errors

Error Response Format

Common Error Codes

Payment-Specific Errors

Transfer-Specific Errors

Troubleshooting Tips

Error Handling Best Practices