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

# Errors

> How the Neo API reports errors — the error envelope, status codes, and the request id to quote to support.

When a request fails, the API returns a non-2xx HTTP status and a consistent error envelope. Read the HTTP status for the category and the `error.code` for the specific, stable reason.

## Error envelope

```json theme={null}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API-key management requires admin role.",
    "details": { "...": "..." }
  },
  "meta": { "request_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d" }
}
```

| Field | Description |
| - | - |
| `error.code` | Stable, machine-readable code — branch on this, not on the message. |
| `error.message` | Human-readable explanation, safe to surface in logs. |
| `error.details` | Optional object with extra context (e.g. which field failed validation). |
| `meta.request_id` | Unique id for this request. Quote it when contacting support. |

## Status codes

| Status | Meaning | What to do |
| - | - | - |
| `400` Bad Request | Malformed request or invalid parameters. | Fix the request shape or values. |
| `401` Unauthorized | Missing, malformed, expired, or revoked credential. | Check the `Authorization` header and [your API key](https://docs.neoagent.io/developers/authentication.md). |
| `403` Forbidden | Authenticated, but the key lacks access to this resource or action. | Confirm the action is allowed for your tenant. |
| `404` Not Found | The resource doesn't exist, or isn't yours. | Check the id; the API never reveals other tenants' resources. |
| `405` Method Not Allowed | The path exists, but not with this HTTP method. The code is `method_not_allowed`. | Use a method from `error.details.allowed_methods`. A cancel is `POST {path}/cancel`, and the message names it when the path has one. |
| `409` Conflict | The request conflicts with current state. | Re-read the resource and retry. |
| `413` Content Too Large | The request body is over the limit for this route, 4 MB on most routes. The code is `payload_too_large`. | Send less. `error.details.max_bytes` names the limit. |
| `422` Unprocessable | The request was well-formed but semantically invalid. | See `error.details` for the offending field. |
| `429` Too Many Requests | You've hit the [rate limit](https://docs.neoagent.io/developers/rate-limits.md). | Back off and retry after `Retry-After`. |
| `5xx` Server Error | Something went wrong on Neo's side. | Retry with backoff; if it persists, contact support with the `request_id`. |

## Nested config fields on agent writes

Wherever `POST /public-api/agents` or `PUT`/`PATCH /public-api/agents/{id}` accepts a config object, it is a **top-level, sibling field** of the agent body and never a child of another: `agent_settings`, `agent_settings_edits`, `toolbox`, `integrations`, `schedule`, `callback_settings`, `actions`, `ticket_conditions` and `time_entry_conditions`.

Which of them a given body accepts is a separate question, answered by that body's schema. `agent_settings_edits` is `PUT`/`PATCH` only, so send the full `agent_settings` on create; and the `POST` body is a discriminated union on `autonomy_type`, so each variant declares its own subset — a `CONVERSATIONAL` create takes no `actions`, a `CHAINED_ACTIONS` create no `toolbox`. Check the schema for your route and `autonomy_type` under **Endpoints** in the sidebar. A field the schema does not declare is ignored rather than rejected.

A tool that reaches an agent only at run time is dropped from `toolbox` on a create or update, and the rest of the write goes through. `GET /public-api/schemas/tools` never lists such a tool, under any filter: a permission group grants it and holds its settings, or Neo adds it by its own rule. To give an agent a tool a permission group grants, grant that group in `integrations`. A tool Neo adds by its own rule cannot be requested; Neo adds it wherever it applies.

Putting one config object directly inside another returns `400 validation_error` and writes nothing. The check reads the immediate keys of each top-level config object, and of each `actions` entry. A container buried deeper than that — inside `agent_settings_edits.custom_instructions`, say — is ignored rather than rejected, which is why you read the agent back after a write. The message names both the field and the depth:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Config field nested one level too deep: `toolbox` inside `agent_settings`. These are top-level fields of the agent body — send them as siblings of the field they are nested in, not inside it. Nothing was written."
  }
}
```

Move the named field out to the top level and resend. This is easiest to get wrong when `custom_instructions` is long, so the closing brace is far from where the object opened.

> [!NOTE]
>
> The update response is the lean agent summary — id, name, state, timestamps — and carries no config. A `200` does not by itself prove a config field was applied; `GET /public-api/agents/{id}` to confirm.

## Changing one permission group

`integrations` merges per integration, but inside one integration `permissions` is a list, and a list replaces the whole list. To change one group, read the agent with `GET /public-api/agents/{id}`, change that group's entry, and send the integration's full `permissions` list back.

A `permissions` list that leaves out a group the agent has on returns `400 validation_error` and writes nothing, because saving it would turn that group off. The message names each group left out. To turn a group off, send it with `"access_level": "DISABLED"`. To turn a whole integration off, send it as `null`, for example `{"integrations": {"cw_psa": null}}`.

## Confirming a scheduled agent's estimated cost

A scheduled agent bills every run its schedule starts. Before one goes on, read its estimate: `GET /public-api/agents/{id}/cost-estimate`, or `GET /public-api/agents/cost-estimate?schedule=<schedule as JSON>` for one you have not created yet. The `estimate` carries `runs_per_day`, `credits_per_run`, `estimated_daily_credits`, `estimated_monthly_credits` (30 days), `share_of_monthly_allowance` and `needs_confirmation`.

When `needs_confirmation` is true (the 30-day estimate is at least 25% of the workspace's monthly credits), a `POST /public-api/agents` with `state` `ENABLED`, or a `PUT`/`PATCH` that moves the agent to `ENABLED`, returns `409` and writes nothing:

```json theme={null}
{
  "error": {
    "code": "estimated_cost_confirmation_required",
    "message": "As saved, this scheduled agent is estimated to use about 2,304 credits a day: 144 runs a day at about 16 credits a run (a typical scheduled agent's run). That is about 69,120 credits in 30 days, 2765% of the 2,500 monthly credits. Nothing was changed. …",
    "details": { "estimate": { "runs_per_day": 144.0, "estimated_daily_credits": 2304, "needs_confirmation": true, "…": "…" } }
  }
}
```

Show the numbers to the person who pays for the credits. Once they agree, send the same body again with `"confirm_estimated_cost": true`. The check runs when a save turns a scheduled agent on (a create is enabled unless it sets `state`) or makes an enabled one run more often. A save that keeps an enabled agent's schedule, or runs it less often, never asks.

> [!TIP]
>
> Treat any `4xx` as a bug in the request to fix, not to retry blindly — except `429`, which you should retry after the `Retry-After` delay, and `409 estimated_cost_confirmation_required`, which you resend with `"confirm_estimated_cost": true` once the person agrees. Retry `5xx` with exponential backoff.

## What's next

> [card] [Rate limits](https://docs.neoagent.io/developers/rate-limits.md)
>
> How much you can call, and how to stay under the limit.


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