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

# Errors and rate limits

> HTTP status codes, problem-details bodies, and Partner API rate limits including Retry-After headers.

Most error bodies follow ASP.NET problem details (`status`, `title`, and often `message`). Always branch on the **HTTP status**, not on a free-text title.

## Status codes

| Status            | When                                                                                                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **200** / **201** | Success. `201` is used when a resource is created (`Location` may be set).                                                                                          |
| **400**           | Validation, future `lastUpdated`, insufficient wallet/subscription, or a business rule. Read `message`. Nothing is charged when a wallet check fails before create. |
| **401**           | Missing, invalid, or inactive API client. Or the wrong regional host.                                                                                               |
| **403**           | Authenticated, but the client is read-only (`canWrite: false`).                                                                                                     |
| **404**           | The key exists conceptually, but not in **this** practice.                                                                                                          |
| **429**           | Rate limit. Honour `Retry-After`.                                                                                                                                   |
| **500**           | Unexpected server error. Retry with backoff; contact support if it persists.                                                                                        |

```json theme={null}
{
  "status": 401,
  "title": "Unauthorized"
}
```

## Rate limits

Limits are **per Client ID** (defaults):

| Window | Default |
| ------ | ------- |
| Minute | 60      |
| Hour   | 1,000   |
| Day    | 10,000  |

On **429**, response headers include:

| Header                  | Meaning                         |
| ----------------------- | ------------------------------- |
| `Retry-After`           | Seconds to wait before retrying |
| `X-RateLimit-Limit`     | Limit that was hit              |
| `X-RateLimit-Remaining` | Remaining in the current window |
| `X-RateLimit-Reset`     | When the window resets          |

<Tip>
  Design for incremental sync and webhooks. Do not poll list endpoints every few seconds.
</Tip>

## Wallet and subscription 400s

Routes that send eForms, KYC, AML, or onboardings may return **400** when the practice has no remaining subscription units or wallet balance. The API does **not** create the job or take a charge in that case. Ask the practice to top up, then retry.

## Idempotency for webhooks

Inbound webhook deliveries include `X-Om-Event-Id`. Treat that as an idempotency key on your side so retries do not double-process. See [Webhooks](/guides/webhooks).