> ## Documentation Index
> Fetch the complete documentation index at: https://developer.notchpay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Learn how to handle errors in the Notch Pay API

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.

<Callout type="info">
  For detailed error codes, examples, and troubleshooting tips, see the [API Errors Reference](/api-reference/errors).
</Callout>

## Understanding API Errors

When an error occurs, the Notch Pay API returns:

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

<CodeGroup>
  ```json Error Response Format theme={null}
  {
    "code": 400,
    "status": "Bad Request",
    "message": "Error message describing what went wrong",
    "errors": {
      "field_name": ["Error description for this field"]
    }
  }
  ```
</CodeGroup>

## Common Error Categories

<CardGroup cols={2}>
  <Card title="Authentication Errors" icon="key" color="#dc2626">
    **Status Codes**: 401, 403

    Occur when there's an issue with your API keys or permissions.

    **Common causes**:

    * Missing API key
    * Invalid API key
    * Insufficient permissions
    * Missing required headers
  </Card>

  <Card title="Validation Errors" icon="triangle-exclamation" color="#dc2626">
    **Status Codes**: 400, 422

    Occur 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
  </Card>

  <Card title="Resource Errors" icon="circle-exclamation" color="#dc2626">
    **Status Codes**: 404, 409

    Occur when the requested resource doesn't exist or there's a conflict.

    **Common causes**:

    * Resource not found
    * Resource already exists
    * Resource in incompatible state
  </Card>

  <Card title="System Errors" icon="server" color="#dc2626">
    **Status Codes**: 429, 500, 503

    Occur due to rate limiting or server-side issues.

    **Common causes**:

    * Rate limit exceeded
    * Server error
    * Service unavailable
  </Card>
</CardGroup>

## Best Practices for Error Handling

<Steps>
  <Step title="Always Check for Errors">
    Don't assume API requests will always succeed. Check for errors in all API responses.

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

  <Step title="Handle Different Error Types">
    Implement specific handling for different types of errors.

    ```javascript theme={null}
    // 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);
    }
    ```
  </Step>

  <Step title="Implement Retry Logic">
    For transient errors like rate limiting or temporary server issues, implement retry logic with exponential backoff.

    ```javascript theme={null}
    // 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++;
        }
      }
    }
    ```
  </Step>

  [//]: # "<Step title=\"Use Idempotency Keys\">"

  [//]: # "  For operations that shouldn't be repeated accidentally (like creating a payment), use idempotency keys."

  [//]: # "  "

  [//]: # "  ```"

  [//]: # "  Idempotency-Key: a-unique-string-for-this-request"

  [//]: # "  ```"

  [//]: # "  "

  [//]: # "  This ensures that if you retry a failed request, the operation won't be performed twice."

  [//]: # "</Step>"

  <Step title="Provide User-Friendly Messages">
    Translate technical error messages into user-friendly messages that help users understand what went wrong and how to fix it.

    ```javascript theme={null}
    // 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.';
    ```
  </Step>
</Steps>

## Logging and Monitoring

<Callout type="warning">
  Always log errors for debugging and monitoring purposes, but be careful not to log sensitive information like card details or API keys.
</Callout>

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](/api-reference/errors) - Detailed error codes and troubleshooting
* [Authentication](/get-started/authentication) - Learn about authentication methods
* [API Response Format](/get-started/responses) - Understand the structure of API responses