> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lumenia.net/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lumenia.net/_mcp/server.

# Errors

The API uses standard HTTP status codes. Error responses are JSON with a `message` field describing what went wrong.

## 400 — Bad Request

The request was syntactically wrong or violated a validation rule.

| Cause                                                            | Fix                                                                                                        |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Required field missing (e.g. a resource `name`)                  | Check the endpoint schema in the [API Reference](/api-reference).                                          |
| Name fails validation (e.g. an org name outside 4–80 characters) | Match the length/format rules documented on the endpoint.                                                  |
| Uploading into a folder that does not exist                      | Create it first with `POST /v1/organizations/{orgId}/folders`, or omit `folder` to use `custom-documents`. |
| Unsupported document file type                                   | Upload one of the [supported types](/documentation/get-started/concepts#documents-and-folders).            |
| Invalid enum value (e.g. a bad `voice`/`transcriber` option)     | Use a value from the relevant options catalog (`GET /v1/integrations/voice/options`).                      |
| Missing `X-Account-Id` on an account-scoped route                | Send the header with an account `id` from `GET /v1/accounts`.                                              |

## 403 — Forbidden

Authentication or authorization failed.

| Cause                                     | Fix                                                                                                         |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Missing or invalid `Authorization` header | Send `Authorization: Bearer YOUR_API_KEY`.                                                                  |
| API key revoked                           | Request a new key from a LumenOne superadmin.                                                               |
| Invalid or unknown `X-Account-Id`         | Use an account `id` from `GET /v1/accounts`. A malformed id, or one not owned by your company, is rejected. |

The body for these errors matches the `InvalidAPIKey` schema.

## 404 — Not Found

The resource doesn't exist, or it isn't visible under the current account/org.

| Cause                                          | Fix                                                                                    |
| ---------------------------------------------- | -------------------------------------------------------------------------------------- |
| Org id not under the account in `X-Account-Id` | Confirm with `GET /v1/organizations` (same header) that the org is listed.             |
| Workspace id not under this account            | A valid id from a different account will not resolve. Re-list under the right account. |
| Document id not in this organization           | Confirm via `GET /v1/organizations/{orgId}/documents`.                                 |
| Tool id not found                              | Confirm via `GET /v1/organizations/{orgId}/tools`.                                     |

> **Info**
>
> `404` vs `403`: you get `403` when the **account** itself is not yours, and `404` when the account is fine but the **org/workspace/document** you named does not live under it. This avoids leaking whether a resource exists in another tenant.

## 500 — Internal Server Error

Something went wrong on our side. The response usually contains a generic message. If you can reproduce it, contact `info@lumenia.net` with:

* The full request URL (with ids redacted if sensitive)
* The request body
* The timestamp and your `X-Account-Id`

## Debugging checklist

When a request fails, work through this list before opening a ticket:

1. **Auth works on its own?** `GET /v1/me` returns `200`.
2. **Account is yours?** `GET /v1/me` (or `GET /v1/organizations`) with the `X-Account-Id` succeeds.
3. **Using ids straight from the API?** Pass back the exact `id` a list/detail endpoint returned — no transformation.
4. **Resources in the same account/org?** The org/workspace/document in the URL must live under the account in the header, and a document and workspace must share an org to embed.
5. **Required fields present and valid?** Check the endpoint's schema in the [API Reference](/api-reference).