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

# Errors

> RFC 9457 problem details, machine-readable codes, and robust error handling.

Errors follow [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457),
served with the media type `application/problem+json`. Branch on the HTTP status
for flow control and on the `code` field for specifics.

## Error shape

```json theme={null}
{
  "type": "urn:creatoraudit:error:not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Account not found.",
  "code": "NOT_FOUND",
  "instance": "/v2/accounts/{id}",
  "request_id": "8f1c2a4e-…"
}
```

<ResponseField name="type" type="string">
  An RFC 9457 URN identifying the error class (`urn:creatoraudit:error:…`).
</ResponseField>

<ResponseField name="title" type="string">
  Short, human-readable summary of the error class.
</ResponseField>

<ResponseField name="status" type="integer">
  The HTTP status code, repeated in the body.
</ResponseField>

<ResponseField name="detail" type="string">
  Human-readable explanation specific to this occurrence.
</ResponseField>

<ResponseField name="code" type="string">
  Stable, machine-readable identifier (for example, `NOT_FOUND`). Branch on this.
</ResponseField>

<ResponseField name="instance" type="string">
  The path of the request that failed.
</ResponseField>

<ResponseField name="request_id" type="string">
  Correlation ID for this request, mirroring the `X-Request-ID` response header.
</ResponseField>

## Validation errors

A `422` (`code: VALIDATION_ERROR`) additionally carries an `errors` array
describing each field that failed validation (an example entry is shown below):

```json theme={null}
{
  "type": "urn:creatoraudit:error:validation-error",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request failed validation.",
  "code": "VALIDATION_ERROR",
  "instance": "/v2/accounts",
  "request_id": "3b9d…",
  "errors": [{ "field": "platform", "message": "must be one of: instagram, tiktok" }]
}
```

## Status codes

| HTTP | `code`                   | Meaning                                    |
| ---- | ------------------------ | ------------------------------------------ |
| 400  | `BAD_REQUEST`            | Malformed request.                         |
| 401  | `UNAUTHORIZED`           | Missing or invalid API key.                |
| 403  | `FORBIDDEN`              | Inactive key or subscription.              |
| 403  | `INSUFFICIENT_SCOPE`     | Key lacks the required scope.              |
| 403  | `QUOTA_EXCEEDED`         | Account quota reached.                     |
| 404  | `NOT_FOUND`              | Resource not found in your organization.   |
| 406  | `NOT_ACCEPTABLE`         | `Accept` header not satisfiable as JSON.   |
| 409  | `CONFLICT`               | State conflict (for example, a duplicate). |
| 415  | `UNSUPPORTED_MEDIA_TYPE` | Write body is not JSON.                    |
| 422  | `VALIDATION_ERROR`       | Request failed validation.                 |
| 429  | `RATE_LIMITED`           | Rate limit exceeded.                       |
| 500  | `INTERNAL_ERROR`         | Unexpected server error.                   |
| 502  | `UPSTREAM_ERROR`         | Upstream provider error.                   |
| 503  | `SERVICE_UNAVAILABLE`    | Temporarily unavailable; retry.            |

Authentication-specific statuses are covered in
[Authentication](/api-reference/authentication); `429` handling and back-off live
in [Rate limits](/api-reference/rate-limits).

## Handle errors robustly

* **Branch on status, then `code`.** Use the HTTP status for coarse flow (retry,
  reauthenticate, surface to the user) and `code` for precise handling — for
  example, distinguishing `INSUFFICIENT_SCOPE` from `QUOTA_EXCEEDED` within `403`.
* **Read `errors` on `422`.** Map each `{ field, message }` back to the input that
  caused it.
* **Always capture `X-Request-ID`.** Log it (or the `request_id` body field) with
  every failure so support can correlate a call to its server-side event.
* **Retry the right ones.** Retry `429` and `503` with back-off and honor
  `Retry-After`; do not blindly retry `4xx` validation or auth errors — fix the
  request instead.
* **Parse defensively.** Treat any non-`2xx` as a problem document and read `code`
  rather than string-matching on `detail`.

```python theme={null}
import httpx

resp = httpx.get(url, headers=headers)
if resp.is_error:
    problem = resp.json()
    request_id = resp.headers.get("X-Request-ID")
    raise RuntimeError(
        f"{resp.status_code} {problem['code']}: {problem['detail']} "
        f"(request_id={request_id})"
    )
```

If you hit an unexpected `5xx`, include the `X-Request-ID` when you contact
[support@creatoraudit.com](mailto:support@creatoraudit.com).