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

# Errors and limits

> One error shape for every endpoint, the codes you can get, and the rate limits.

## Error shape

Every error has the same body:

```json theme={null}
{
  "error": {
    "code": "limit_reached",
    "message": "2K video is not included in your plan.",
    "details": { "limit_code": "render_2k" }
  }
}
```

Branch on `code`, show `message` to people, and read `details` when it's there.

## Codes

| Status | `code` | Meaning |
| - | - | - |
| 400 | `invalid_request` | The request body or a parameter is wrong. `details` names the field. |
| 401 | `unauthorized` | No API key, or the key is unknown or revoked. |
| 402 | `paid_plan_required` | The organization isn't on a paid plan. |
| 402 | `limit_reached` | A plan limit is reached. `details.limit_code` says which. |
| 403 | `forbidden` | The key's owner isn't allowed to do this. |
| 404 | `not_found` | No such demo, question or endpoint in this organization. |
| 409 | `conflict` | The demo can't change any more, a request with this `idempotency_key` is still running, or a webhook endpoint with this URL already exists. |
| 410 | `gone` | The question was already answered or has expired. |
| 422 | `needs_answers` | The task needs answers first. See [questions](https://developers.demosmith.ai/questions.md#before-the-demo-questions-about-the-task). |
| 422 | `not_feasible` | The task can't be recorded as written. `message` says why. |
| 422 | `login_not_accepted_here` | An assistant tried to send a login or code. `details.answer_url` is where a person can enter it. |
| 429 | `rate_limited` | Too many requests. Wait for the `Retry-After` header. |
| 503 | `unavailable` | Demosmith is busy or the API is paused. Try again shortly. |

## Rate limits

| What | Limit |
| - | - |
| All requests, per API key | 300 per minute |
| `POST /demos` and `POST /demos/check` | 20 per minute |

Assistants share the same limits. A `429` comes with a `Retry-After` header in seconds.

## Retrying safely

* `GET` requests are always safe to retry.
* Add an `idempotency_key` to `POST /demos`. Sending the same key again returns the first demo (`200`) instead of creating another.
* Retry `429` and `503` after a short wait. Don't retry `4xx` errors without changing the request.


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