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

# Errors

> The single error envelope used by every v2 endpoint

Audienceful uses conventional HTTP status codes to indicate the success or failure of a request. Codes in the `2xx` range indicate success, `4xx` codes indicate a problem with the request (a missing field, a permission issue, a conflict, etc.), and `5xx` codes indicate an error on Audienceful's side.

Every non-`2xx` v2 response uses a single, consistent error envelope:

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "invalid",
    "message": "The request body failed validation.",
    "errors": [
      { "field": "email", "message": "This field is required." }
    ]
  },
  "request_id": "9f2c1a7e5b8d4f31a0c6e2d9b7a4f108"
}
```

<ResponseField name="error" type="object">
  <Expandable title="properties" defaultOpen="true">
    <ResponseField name="type" type="string">
      A broad classification of the error. One of the [error types](#error-types) below.
    </ResponseField>

    <ResponseField name="code" type="string">
      A machine-readable slug for the specific error, useful for programmatic handling.
    </ResponseField>

    <ResponseField name="message" type="string">
      A human-readable summary of what went wrong.
    </ResponseField>

    <ResponseField name="errors" type="array">
      Present only for `validation_error`. A list of the individual fields that failed validation, each with a `field` and a `message`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="request_id" type="string">
  The id of the request, matching the `X-Request-Id` response header. Include it when contacting support.
</ResponseField>

## Error types

| `type`                  | Typical status        | Meaning                                                                                                   |
| ----------------------- | --------------------- | --------------------------------------------------------------------------------------------------------- |
| `validation_error`      | `400`                 | The request body failed validation. See `errors[]` for per-field detail.                                  |
| `invalid_request_error` | `400` / `405` / `415` | The request was malformed, used an unsupported method, or sent an unsupported media type.                 |
| `authentication_error`  | `401`                 | The API key is missing or invalid.                                                                        |
| `permission_error`      | `403`                 | The API key is valid but lacks the [scope](/authentication#scopes) required for this endpoint.            |
| `not_found_error`       | `404`                 | The requested resource does not exist in this workspace.                                                  |
| `conflict_error`        | `409`                 | The request conflicts with existing state (e.g. a duplicate email, or an in-progress idempotent request). |
| `rate_limit_error`      | `429`                 | You've exceeded a [rate limit](/throttling).                                                              |
| `api_error`             | `500`                 | Something went wrong on Audienceful's side.                                                               |

<Tip>Validation errors (`400`) are the ones you'll see most often while integrating. Read the `errors[]` array to see exactly which fields were rejected and why.</Tip>