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

# Errors

> The problem+json error shape, common status codes, and named problems you'll hit.

When a request fails, Flowyte returns an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)
**problem+json** body with the `application/problem+json` content type. The HTTP status is the
source of truth; the body adds machine-readable detail.

## The problem shape

```json theme={null}
{
  "type": "about:blank",
  "title": "Validation failure",
  "status": 400,
  "detail": "name is required",
  "instance": "/api/v1/agents",
  "code": "validation_error",
  "errors": [
    { "field": "name", "message": "is required" }
  ]
}
```

| Field      | Meaning                                                            |
| ---------- | ------------------------------------------------------------------ |
| `status`   | HTTP status code (also on the response).                           |
| `title`    | Short, human-readable summary of the problem type.                 |
| `detail`   | Explanation specific to this occurrence.                           |
| `code`     | Stable machine string for branching (e.g. `no_published_version`). |
| `errors[]` | Field-level validation errors (`field`, `message`), when relevant. |

<Tip>
  Branch on `status` and `code`, not on `detail` or `title` — those wording may change.
</Tip>

## Common statuses

| Status                  | When                                                                                          |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| `400 Bad Request`       | Malformed or invalid request body; `errors[]` lists the offending fields.                     |
| `401 Unauthorized`      | Missing or invalid key/session. Check `Authorization: Bearer flowyte_sk_…`.                   |
| `403 Forbidden`         | Org mismatch, insufficient scope, disallowed origin — or a **reserved** endpoint (see below). |
| `404 Not Found`         | The resource doesn't exist **in your org's scope**.                                           |
| `409 Conflict`          | Duplicate name, a publish race, or a stale `If-Match` version.                                |
| `422 Unprocessable`     | Semantically invalid — e.g. a language your plan's speech engine doesn't support.             |
| `429 Too Many Requests` | Rate-limited. Honor `Retry-After` and the `RateLimit-*` headers.                              |

## Reserved endpoints return 403

Some endpoints in the contract are **reserved** (planned ahead of release). Calling one returns
**`403`, not `404`** — the route exists but isn't open to you yet. If a correctly-authenticated,
correctly-scoped call returns `403`, check whether the endpoint is reserved before assuming a
permissions bug. The same `403` also covers genuine scope and cross-org denials.

## Named problems

A few problems carry a specific `code` worth handling:

| `code`                      | Status | Meaning                                                                                                                                            |
| --------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `no_published_version`      | `409`  | You requested a published-mode session (e.g. a non-draft talk token) but the agent has never been published. Publish it, or use `draftMode: true`. |
| `integration_unavailable`   | `400`  | The provider's OAuth app isn't configured for this deployment yet.                                                                                 |
| `integration_not_connected` | `409`  | A config helper needs a connected provider (e.g. resolving a Sheet before Sheets is connected).                                                    |
| `sheet_not_accessible`      | `404`  | The spreadsheet link is wrong or hasn't been shared with the connected account.                                                                    |
| `file_expired`              | `404`  | An uploaded `fileId` was garbage-collected before it was attached. Re-upload.                                                                      |
| `file_too_large`            | `413`  | The upload exceeds the 25 MB limit.                                                                                                                |

## Optimistic concurrency (409 on `PATCH /agents/{id}`)

Agent autosave uses an `If-Match` version. If you send a stale version, the server responds
`409` **with the current agent state and version** in the body. Rebase: refetch, re-apply your
pending edits, and retry with the new version.

For status codes per endpoint, see the [API Reference](/api-reference/introduction).