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

# Errors

> The error envelope and the status codes the API returns.

Errors are returned as JSON with a consistent envelope and a matching HTTP status code.

## Error envelope

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key"
  }
}
```

## Status codes

| Code            | HTTP | Meaning                                                                    |
| --------------- | ---- | -------------------------------------------------------------------------- |
| `unauthorized`  | 401  | Missing or invalid API key                                                 |
| `forbidden`     | 403  | Key lacks the required scope (e.g. a publishable key on a secret endpoint) |
| `plan_required` | 402  | The endpoint requires a paid plan                                          |
| `bad_request`   | 400  | Invalid parameters — the message says what                                 |
| `not_found`     | 404  | The resource isn't in your workspace                                       |
| `internal`      | 500  | Something went wrong on our side                                           |

<Note>
  Analytics endpoints return a specific `402` message when the workspace isn't on a paid plan:
  *"The analytics API requires a paid plan (revenue reporting is a paid feature)."*
</Note>

## Common causes

<AccordionGroup>
  <Accordion title="401 unauthorized">
    The `Authorization` header is missing or malformed, or the key was revoked. It must read
    `Authorization: Bearer <key>` and the key must be at least 24 characters.
  </Accordion>

  <Accordion title="403 forbidden">
    You used a publishable (`pk_`) key on an endpoint that needs a secret (`lk_`) key. Only the
    referral enroll and report-signup endpoints accept publishable keys.
  </Accordion>

  <Accordion title="402 plan_required">
    The workspace is on the Free tier. The API is a paid-plan feature — upgrade to generate and use
    keys.
  </Accordion>

  <Accordion title="400 bad_request">
    A parameter is invalid — for example a malformed date (`Invalid \`from\` date (use ISO 8601)`)
            or `from`not before`to\`.
  </Accordion>
</AccordionGroup>