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

# Error handling

> Standard error format and recovery patterns

All Natural API errors follow a standard JSON:API-style format with stable public codes and safe display copy.

## Error response format

Every error response contains an `errors` array with one or more error objects:

```json theme={null}
{
  "errors": [
    {
      "code": "insufficient_funds",
      "detail": "Insufficient funds.",
      "status": "409",
      "meta": {
        "supportId": "req_a1b2c3d4e5f6"
      }
    }
  ]
}
```

Each error object contains:

| Field    | Type   | Required | Description                                                            |
| -------- | ------ | -------- | ---------------------------------------------------------------------- |
| `code`   | string | Yes      | Stable lower-snake-case public error code (e.g., `insufficient_funds`) |
| `detail` | string | Yes      | Safe user-facing error message                                         |
| `status` | string | Yes      | HTTP status code as a string                                           |
| `source` | object | No       | Location of the invalid request value, such as `source.pointer`        |
| `meta`   | object | Yes      | Metadata containing `supportId` for troubleshooting                    |

### Metadata

Public error responses include `meta.supportId` by default. Internal/upstream metadata is kept in logs and traces, correlated by `supportId`.

## Validation errors

Validation errors may include `source.pointer` for API clients:

```json theme={null}
{
  "errors": [
    {
      "code": "invalid_value",
      "detail": "email: Invalid email address",
      "status": "422",
      "source": {
        "pointer": "/data/attributes/email"
      },
      "meta": {
        "supportId": "req_a1b2c3d4e5f6"
      }
    }
  ]
}
```