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

# Errors

> The shape of an error response, what each status code means and the messages you are most likely to see.

When a request fails, the API answers with an HTTP status code and a JSON body that says why. Use the status code to decide what your program does next, and show or log the `detail`.

## The error body

```json theme={null}
{ "detail": "Description of what went wrong" }
```

`detail` is usually a sentence. A few answers differ:

| Answer | Body |
| - | - |
| `409` of a busy conversation | `{"detail": {"message": "This chat already has a run in progress", "active_run_id": "…"}}` |
| `429` of a request-rate limit | `{"detail": {"reason": "rate_limited", "scope": "…", "retry_after_seconds": …}}` |
| A missing or empty required field | `400` with `Required fields are missing or empty: …`, naming the fields |
| A file rejected by `POST /chat` | An `error` field instead of `detail`. See [Form fields](https://docs.neuralfactory.ai/api-reference/runs.md#form-fields) |

## Status codes

| Code | Meaning | What to do |
| - | - | - |
| `200` | Success | |
| `202` | Accepted: the run is going | Poll, stream or wait for the webhook with its `run_id`. See [Runs and results](https://docs.neuralfactory.ai/api-reference/runs.md) |
| `400` | Bad request: a missing field, a message too long, a refused `callback_url`, a malformed body | Fix the request. Do not retry it unchanged |
| `401` | No token, an invalid or expired token, or a key that was turned off or deleted | Get a new token. See [Authentication](https://docs.neuralfactory.ai/api-reference/authentication.md#when-authentication-fails) |
| `403` | Outside the key's permissions or scope, an endpoint keys cannot use, or (SaaS) a frozen, paused or suspended subscription, or API keys on the **Free** plan | Check the key's permissions, or the account's subscription |
| `404` | Not found, or no longer kept | Check the id |
| `409` | Conflict: the conversation already has an active run, the agent is not published, or a resume did not match the pending requests | Read `detail`. For a busy conversation, attach to `active_run_id` |
| `413` | A file, or the files of one request, are too large | Send smaller or fewer files |
| `429` | A limit was reached: too many runs at once, a request-rate limit, or used-up usage or a spend limit | Wait for `Retry-After` when it is present. See [Rate and concurrency limits](https://docs.neuralfactory.ai/api-reference/rate-limits.md) |
| `500` | Server error. Also returned when an observed run failed within the observe window | For a run, read its `error`. Otherwise retry later with the same `idempotency_key` |

## Messages you may see

### Starting a run

| Status | `detail` | Why |
| - | - | - |
| `404` | `Agent not found` | No agent has this `agent_id` |
| `403` | `You don't have access to this agent` | The agent is outside the key's scope |
| `403` | `You don't have access to this chat` | The `chat_id` belongs to someone else |
| `409` | `This agent is not published yet` | The agent is a draft. Publish it in the web app |
| `409` | `This chat already has a run in progress` | The `chat_id` has an active run. See [One active run per conversation](https://docs.neuralfactory.ai/api-reference/runs.md#one-active-run-per-conversation) |
| `400` | `Message is too long: … tokens, the agent's model allows … tokens` | The message takes more than half the context window of the agent's model |
| `429` | `You already have … agent runs in progress (your limit is …). …` | Too many runs at once for the key's creator |
| `429` | `Your organization already has … agent runs in progress (limit …). Please wait for one to finish.` | Too many runs at once for the organization |

### Account and usage (SaaS)

| Status | `detail` |
| - | - |
| `403` | `API keys are not available on the Free plan. Upgrade your plan to use them.` |
| `403` | `This account is frozen. Choose a plan to unfreeze it.` |
| `403` | `This organization is frozen. Ask an organization admin to unfreeze it.` (a Member's key) |
| `403` | `Your subscription is paused. Resume it to continue.` |
| `403` | `Your subscription has been suspended. Please contact support.` |
| `403` | `Your contract ended on YYYY-MM-DD. Contact Neural Factory to continue.` (or `Your demo ended …`) |
| `429` | `Your included usage is used up. Buy a top-up, or upgrade your plan, to continue.` |
| `429` | `Your included usage is used up. Ask an organization admin to buy a top-up.` (a Member's key) |
| `429` | `Your spend limit for this period is reached. Ask an organization admin to raise it.` (a Member's key; an Admin's reads `… Raise it on Spend limits.`) |

On **Business**, the spend limit in that last message is the member's top-up limit: how much of the organization's top-ups one member may use per billing period.

A `429` for usage has no `Retry-After`: it does not clear by waiting a few seconds.

### Usage limits (Enterprise)

By default, `POST /chat` with an API key on Enterprise is not checked against usage limits and budgets; your deployment can turn that check on. Starting a workflow run is always checked, for keys too. A run past a limit answers `429` with one of these:

| `detail` |
| - |
| `Your usage limit for this month is reached. Ask an administrator to raise it.` |
| `The organization's budget for this month is reached. Ask an administrator to raise it.` |

An Admin's key reads `… Raise it on Spend limits.` instead of the last sentence.

### Pauses and follow-ups

| Status | `detail` |
| - | - |
| `409` | `Resume must decide exactly the pending interrupts: […]` |
| `409` | `Run is not awaiting input or a decision was already recorded` |
| `409` | `Run is no longer active, or its follow-up queue is full (max 5). If the run finished, send the message normally.` |
| `400` | `Body must be {'message': <text>}` (a follow-up whose message is only spaces) |

## Related

* [Authentication](https://docs.neuralfactory.ai/api-reference/authentication.md)
* [Rate and concurrency limits](https://docs.neuralfactory.ai/api-reference/rate-limits.md)
* [Common errors in the web app](https://docs.neuralfactory.ai/help/troubleshooting/common-errors.md)


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