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

# Errors & rate limits

> Status codes, error handling, retries, and rate limits for the Biomni API

## Status codes

| Code          | Meaning                        | What to do                                                                                                                        |
| ------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `200` / `201` | Success                        | —                                                                                                                                 |
| `204`         | Success, no body (e.g. revoke) | —                                                                                                                                 |
| `401`         | Unauthorized                   | Key is missing, malformed, revoked, or expired. Check the `Authorization` header and the key's status in **Settings → API Keys**. |
| `403`         | Forbidden                      | Authenticated, but not allowed for this resource in this workspace. A key only has your permissions, in its own workspace.        |
| `404`         | Not found                      | The project/task/file id doesn't exist in this workspace.                                                                         |
| `422`         | Validation error               | The request body is malformed or missing fields. `error.message` says what's wrong, and `error.param` names the offending field.  |
| `429`         | Rate limited                   | You're sending too fast. Back off and retry (see below).                                                                          |
| `5xx`         | Server error                   | Transient — retry with backoff.                                                                                                   |

Every error returns the same JSON envelope: an `error` object with a `type`, a
machine-readable `code`, a human-readable `message`, and (on validation errors)
the offending `param`.

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "Project proj_xxxxxxxxxx not found."
  }
}
```

## Retries and backoff

Retry `429` and `5xx` responses with **exponential backoff**. Do **not** retry
`4xx` other than `429` — fix the request instead.

```python theme={null}
import time, requests

def request_with_retry(method, url, *, headers, max_retries=5, **kwargs):
    for attempt in range(max_retries):
        resp = requests.request(method, url, headers=headers, **kwargs)
        if resp.status_code < 400:
            return resp
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(2 ** attempt)  # 1s, 2s, 4s, 8s, 16s
            continue
        resp.raise_for_status()  # non-retryable 4xx
    resp.raise_for_status()
    return resp
```

## Rate limits

Limits apply per workspace to keep the platform stable. If you exceed them you
get a `429`; slow down and retry with backoff.

For sustained high-volume workloads (large batch pipelines), keep concurrency
bounded and space out your calls. If you expect to run well beyond normal usage,
contact [support@phylo.bio](mailto:support@phylo.bio) so we can make sure your
workspace is provisioned for it.

## Key lifecycle errors

* **`401` right after creating a key** — confirm you copied the full API key
  (it's shown only once) and sent it as `Authorization: Bearer <your-api-key>`.
* **`401` on a previously working key** — it may have been **revoked** or
  **expired**. Create a new key and update your integration.