Get started

Errors

Common failure modes and how to fix them.

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.

CauseFix
Required field missing (e.g. a resource name)Check the endpoint schema in the 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 existCreate it first with POST /v1/organizations/{orgId}/folders, or omit folder to use custom-documents.
Unsupported document file typeUpload one of the supported types.
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 routeSend the header with an account id from GET /v1/accounts.

403 — Forbidden

Authentication or authorization failed.

CauseFix
Missing or invalid Authorization headerSend Authorization: Bearer YOUR_API_KEY.
API key revokedRequest a new key from a LumenOne superadmin.
Invalid or unknown X-Account-IdUse 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.

CauseFix
Org id not under the account in X-Account-IdConfirm with GET /v1/organizations (same header) that the org is listed.
Workspace id not under this accountA valid id from a different account will not resolve. Re-list under the right account.
Document id not in this organizationConfirm via GET /v1/organizations/{orgId}/documents.
Tool id not foundConfirm via GET /v1/organizations/{orgId}/tools.

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 [email protected] 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.