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

# Errors

> Error envelope and common error codes.

Failures return HTTP 4xx/5xx with a JSON body:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      { "field": "amount", "message": "Input should be greater than 0" }
    ]
  }
}
```

Always branch on `error.code` rather than the human `message` — codes are
stable, messages may change.

## Common codes

| HTTP | `code` | Meaning |
| - | - | - |
| 400 | `INVALID_ID` | The path id is not a valid ObjectId / UUID. |
| 400 | `INVALID_BODY` | The request body is not a JSON object (empty, malformed, `null`, an array, a form upload). |
| 400 | `INVOICE_REJECTED` | Business rule violation while creating an invoice. |
| 400 | `MISSING_HEADER` / `INVALID_HEADER` | Required header missing or malformed (e.g. `x-uniq-id`). |
| 400 | `SANDBOX_UNSUPPORTED` | Endpoint is live-only; called with a sandbox key. See [Sandbox](/sandbox). |
| 400 | `SANDBOX_ONLY` | Endpoint is sandbox-only (e.g. simulating a payment); called with a live key. |
| 401 | `UNAUTHORIZED` | Missing or invalid `x-api-key`. |
| 403 | `PAYOUTS_DISABLED` | IP not whitelisted for payouts. |
| 404 | `NOT_FOUND` | The requested resource is invisible to this merchant. |
| 409 | `DUPLICATE` | Same `x-uniq-id` already used. |
| 422 | `VALIDATION_ERROR` | Body did not match the schema. `details` lists the failing fields. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.