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

# Errors and conventions

> What the API returns when something is wrong, and what to do about it.

## Status codes

| Code  | Means                                                | Do                                         |
| ----- | ---------------------------------------------------- | ------------------------------------------ |
| `200` | Done — or an idempotent repeat                       | Nothing                                    |
| `201` | Created                                              | Nothing                                    |
| `400` | Your payload                                         | Read `detail`; do not retry unchanged      |
| `401` | Key missing, revoked or expired                      | Check the header, then the console         |
| `403` | Key lacks the scope, or is not a reseller credential | Mint a key with the scope                  |
| `404` | Not yours, or not there                              | See below                                  |
| `429` | Too fast                                             | Back off and retry                         |
| `502` | A tool server did not answer                         | Check your MCP endpoint                    |
| `5xx` | Ours                                                 | Retry with backoff; tell us if it persists |

Errors carry a human-readable `detail`:

```json theme={null}
{ "detail": "This API key is missing the \"knowledge:write\" scope." }
```

## 404 is deliberately ambiguous

A tenant that belongs to another partner and a tenant that does not exist both
return 404. A 403 would confirm the id is real, which would let anyone
enumerate a competitor's customer list one guess at a time. Do not infer
existence from the status code.

## Retries and idempotency

Tenant provisioning is idempotent on `(you, external_ref)` — retry it freely
after a timeout. Knowledge sync is a full replace, so re-sending the same set
converges rather than duplicating.

For everything else, retry `429` and `5xx` with exponential backoff. Do not
auto-retry a `400`.

## Async work

Document upload and website crawl return before the work is done. Poll the job
before telling a merchant their knowledge is ready.

## Versioning

The surface is `/api/v1/`. Additive changes — new optional fields, new
endpoints — can arrive without notice, so parse defensively and ignore fields
you do not recognise. Removals and type changes will not happen inside `v1`
without notice to you first.