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

# Errors

> The error format and error codes of the events endpoints and the MCP server, which errors are safe to retry, and how to handle rate limits (429).

Most errors return JSON with a stable code and a message:

```json theme={null}
{ "error": { "code": "INVALID_EVENT", "message": "Invalid event payload" } }
```

| Field | Notes |
| - | - |
| `code` | A stable, machine-readable code. Branch on this. |
| `message` | A human-readable text. The wording can change; do not branch on it. |
| `issues` | Server events only: up to five validation issues, each with a `path` and a `message` |

Success bodies are not wrapped. For example, `POST /v0/events` returns `202` with `{ "accepted": 3 }`.

## Error codes

| Status | Code | Meaning | Retry |
| - | - | - | - |
| `400` | `INVALID_EVENT` | The body or an event failed validation. The whole batch is refused. | No. Fix the event. |
| `400` | `MIXED_CHANNELS` | Events: a batch mixes `server` events with `web` or `app` events | No. Send them in separate requests. |
| `400` | `INVALID_PROPERTIES` | Profile properties: a key, a value or a `user_id` failed validation | No. Fix the property. |
| `401` | `UNAUTHORIZED` | The key is missing, malformed or unknown. Or the key is in the wrong header: a secret key or an API key in `X-Publishable-Key`, a publishable key in `Authorization`, or both headers in one request. | No |
| `402` | `SUBSCRIPTION_REQUIRED` | MCP only: the workspace has no active subscription or trial | No |
| `403` | `FORBIDDEN` | The origin or page URL does not match the project, an API key or token has no usable scopes, or an API key has no `profiles:write` | No |
| `403` | `SECRET_KEY_FROM_BROWSER` | Events: a request with an `Origin` header (a browser) used the secret key | No. Send server events from your backend only. |
| `403` | `SECRET_KEY_REQUIRED` | Events: `server` events were sent with the publishable key | No. Use the secret key. |
| `403` | `PUBLISHABLE_KEY_REQUIRED` | Events: `web` or `app` events were sent with the secret key | No. Use the publishable key. |
| `403` | `WORKSPACE_SUSPENDED` | The project's workspace is suspended and does not accept events (with the publishable key or the secret key) | No |
| `404` | `NOT_FOUND` | Profile properties: the key belongs to another project | No |
| `413` | `TOO_LARGE` | Server events: the batch is larger than 256 KB. Profile properties: the body is larger than 64 KB (one profile) or 200 KB (batch). | No. Send smaller batches. |
| `429` | `RATE_LIMITED` | Events, and profile property writes with an API key: the project sent too many events or writes this minute | Yes, after `Retry-After`. See [rate limits](#rate-limits-429). |
| `429` | `TOO_MANY_REQUESTS` | MCP and profile properties: the key, app or workspace budget is used up | Yes, after `Retry-After`. See [rate limits](#rate-limits-429). |
| `500` | `INTERNAL` | An unexpected error. The body has a `request_id`. | Yes, with backoff |

Every response has an `X-Request-ID` header. Include it when you contact support.

## Responses without a body

Some responses have a status code and no JSON body:

| Endpoint | Status | Meaning |
| - | - | - |
| `POST /v0/identify` | `400`, `401`, `403` | Invalid body, bad publishable key, or a page URL or origin that does not match the project |
| `GET /v0/tracking/config` | `401`, `403` | Bad publishable key, or an origin that does not match the project |
| `POST /mcp` | `401` | Missing or invalid key or token. The `WWW-Authenticate` header points OAuth clients to the [metadata](https://docs.manalens.dev/mcp/oauth.md#oauth-endpoints). |
| `POST /mcp` | `403` | The request has a browser `Origin` header. Call the MCP server from an MCP client, not from a web page. |

The [OAuth endpoints](https://docs.manalens.dev/mcp/oauth.md#oauth-endpoints) use the OAuth error format: `{ "error": "invalid_client", "error_description": "..." }`.

## Rate limits (429)

A `429` response means a limit is used up for now. The request itself is fine: send it again later, unchanged.

| Limit | Applies to | Code | `Retry-After` |
| - | - | - | - |
| Events per project per minute | `POST /v0/events` and `POST /v0/identify`. Server events have their own count. Profile property writes with an API key count as server events. | `RATE_LIMITED` | Seconds until the next minute starts |
| Key, app or workspace budget | `POST /mcp` and profile properties | `TOO_MANY_REQUESTS` | `60` |
| OAuth client registration, authorization and token requests | The [OAuth endpoints](https://docs.manalens.dev/mcp/oauth.md#oauth-endpoints) | `temporarily_unavailable` in the OAuth format. The authorization page shows the error instead. | `60` |

Every `429` has a `Retry-After` header with a number of seconds. The events limit is per minute and far above normal traffic, so a `429` there usually means a loop or a backfill that sends too fast.

To handle a `429`:

1. Read `Retry-After` and wait at least that many seconds. If the header is missing, use exponential backoff (1, 2, 4, 8 seconds) with some random jitter.
2. Send the same request again, with the same `message_id` for events, so that a retry does not count twice.
3. Stop after a few tries and keep the events to send later. Do not retry at once in a tight loop: each try counts against the same limit.
4. For a backfill, send fewer events per minute, or spread the batches out.

```ts theme={null}
async function send(body: unknown, tries = 5) {
  for (let attempt = 0; attempt < tries; attempt++) {
    const response = await fetch('https://YOUR_COLLECTOR_ENDPOINT/v0/events', {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.ANALYTICS_SECRET_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify(body), // the same body, and the same message_id values, on every try
    });
    if (response.ok) return response.json();
    if (response.status !== 429 && response.status < 500) {
      const error = await response.json().catch(() => null);
      throw new Error(`Refused: ${response.status} ${error?.error?.code ?? ''}`);
    }
    const retryAfter = Number(response.headers.get('Retry-After'));
    const seconds = retryAfter > 0 ? retryAfter : 2 ** attempt + Math.random();
    await new Promise(resolve => setTimeout(resolve, seconds * 1000));
  }
  throw new Error('Still failing after retries: keep the events and send them later');
}
```

## Handle errors well

1. **Branch on `code`**, not on `message` or the status alone.
2. **Retry only `429` and `5xx`.** Wait for the `Retry-After` seconds on `429`. Use exponential backoff on `5xx`.
3. **Keep the same `message_id` on a retry.** Reports count each `message_id` once, so a retry does not count twice. See [idempotency](https://docs.manalens.dev/api/idempotency.md).
4. **Do not retry other `4xx` codes** without a change. They fail the same way again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.