> ## Documentation Index
> Fetch the complete documentation index at: https://docs-alpha.pepay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error envelopes, status codes, and debugging guidance.

## Overview

Pepay returns JSON error responses. For debugging, always log:

* HTTP status code
* an error `code` / `error_code` when present
* an error message (`message` or `error.message`)
* request id headers when present (`x-request-id`, `request-id`)

If you’re using the SDK, errors are normalized into typed exceptions and include safe retry behavior for retryable cases.

## Authentication

Some errors happen before authentication succeeds (for example, missing/invalid headers). Others are authorization errors (`403`) after the request is authenticated but lacks permissions or scope.

## Request

When reporting an issue, include:

* the endpoint + method
* the request id header (if present)
* a sanitized excerpt of the response body (do not include API keys or session tokens)

Example request (invalid API key):

```bash theme={null}
BASE_URL=${PEPAY_API_URL}

curl "$BASE_URL/api/v1/invoices?limit=1" \
  -H "x-api-key: sk_live_invalid"
```

## Response

Error envelopes may vary slightly by endpoint. Common shapes include:

`success=false` envelope:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "API_KEY_INVALID",
    "message": "Invalid API key"
  }
}
```

Legacy `{error, code}` envelope:

```json theme={null}
{
  "error": "Failed to fetch wallets",
  "code": "INTERNAL_SERVER_ERROR"
}
```

## Errors

| Status | Meaning                              | Typical fix                    | Retry?            |
| ------ | ------------------------------------ | ------------------------------ | ----------------- |
| `400`  | Validation / business rule violation | Fix the request body/params    | No                |
| `401`  | Missing/invalid credentials          | Check headers and token format | No                |
| `403`  | Authenticated but forbidden          | Verify permissions/scope       | No                |
| `404`  | Not found                            | Verify IDs and environment     | No                |
| `429`  | Rate limited                         | Backoff; respect `Retry-After` | Yes (after delay) |
| `5xx`  | Transient server error               | Retry with backoff if safe     | Often             |

## Examples

Example (SDK error handling):

```ts theme={null}
import { Pepay } from 'pepay';

const pepay = new Pepay({ apiKey: process.env.PEPAY_API_KEY! });

try {
  await pepay.merchants.invoices.list({ limit: 1 });
} catch (err) {
  // Log status + code/message, but never log secrets.
  console.error(err);
}
```

Next: [Merchant APIs](/api-spec/merchant/api-keys)