# Errors


All errors keep the [envelope](/concepts/envelope) shape with
`status: "error"`. The HTTP status code is mirrored in `code`.

## 401 Unauthenticated

Returned when the bearer token is missing, invalid, or expired.

```json
{
  "message": "Unauthenticated."
}
```

**Fix:** get a fresh token from [`POST /api/v2/auth/login`](/getting-started/authentication)
and resend the request with `Authorization: Bearer <token>`.

## 404 Not Found

Returned when the requested id does not exist for your account.

## 406 Not Acceptable

Returned when the request does not send `Accept: application/json`.

**Fix:** always send both:

```
Content-Type: application/json
Accept: application/json
```

## 409 Conflict

Returned by a resource-create endpoint when an `Idempotency-Key` is reused with a
**different** request body, or when a duplicate of a still in-flight create
arrives with the same key.

**Fix:** use a fresh key for a genuinely new create, and reuse a key only to
retry the identical request. See [Idempotency](/concepts/idempotency).

## 422 Validation error

Returned when the request body fails validation. The `errors` object maps each
invalid field to an array of human-readable messages.

```json
{
  "status": "error",
  "code": 422,
  "message": "Validation error.",
  "data": [],
  "errors": {
    "field_name": [
      "The field_name field is required.",
      "The field_name field is required to be string type."
    ]
  }
}
```

**Fix:** read `errors`, correct the named fields, and retry.

Common `422` cases on the write endpoints:

- **Audience create** - a filter value or `project_id` that does not exist.
- **Activation create** - no credentials available (neither caller-supplied nor
  stored on the connection), an audience below the 500-unique-device minimum to
  activate, or a prohibited identity field (`partner_id`, `partner_name`,
  `pricing_model`) in the body. See
  [Activate an Audience](/guides/activate-an-audience).

## 429 Too Many Requests

Returned when you exceed the per-token rate limit (120 reads/min, 30 writes/min).
The response includes a `Retry-After` value in seconds.

**Fix:** wait `Retry-After` seconds, then retry. On a create, resend the same
`Idempotency-Key` so the retry cannot double-create. See
[Polling and Rate Limits](/guides/polling-and-rate-limits).

## Handling errors

1. Check the HTTP status code first.
2. On `422`, iterate `errors` and surface field-level messages to your user.
3. On `401`, refresh the token and retry once.
4. Log `message` for diagnostics, but branch on `status` + `code`.