For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Contact us
DocumentationAPI Reference
DocumentationAPI Reference
  • Get started
    • Introduction
    • Authentication
    • Concepts
    • Quickstart
    • Errors
Contact us
LogoLogo
On this page
  • 400 — Bad Request
  • 403 — Forbidden
  • 404 — Not Found
  • 207 — Multi-Status (partial success)
  • 500 — Internal Server Error
  • Debugging checklist
Get started

Errors

Common failure modes and how to fix them.
Was this page helpful?
Previous
Built with

The API uses standard HTTP status codes. Most error responses are JSON with a success: false flag and a message field.

400 — Bad Request

The request was syntactically wrong or violated a validation rule.

CauseFix
Wrong slug format in URL pathURL paths require hex-encoded slugs. See Concepts.
Wrong slug format in body / query / docpathBodies, query params, and docpath leading segments use the original slug.
addToWorkspaces slug belongs to a different orgAll workspace slugs must belong to the org in the URL.
Docpath in adds/deletes/from/to/files belongs to another orgCross-org operations are rejected. Use the org that owns the documents.
Required field missing (e.g. country, number_type)Check the endpoint schema in the API Reference.
Invalid status filter on GET /v1/org/{orgSlug}/number-requestsUse one of the documented enum values.
scope query passed without organization_id on /v1/numbersscope is only valid when filtering by org.

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.
X-Account-Id belongs to a different companyThe account must belong to your company.

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 doesn’t belong to the account in X-Account-IdConfirm with GET /v1/orgs (with the same header) that the org is listed.
Workspace doesn’t belong to the org you expectedConfirm via GET /v1/org/{orgSlug}/workspaces.
Number request id doesn’t exist in this orgNumber requests are org-scoped — the id from one org won’t resolve in another.
Document name not foundThe docName path param must be the bare filename, no path separators.

207 — Multi-Status (partial success)

Returned by DELETE /v1/org/{orgSlug}/document/remove-files when some — but not all — documents could be removed. The body lists purged (succeeded) and failed (with per-file error reasons). Retry only the failed entries.

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 slugs 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/auth returns 200.
  2. Account is yours? GET /v1/orgs with X-Account-Id returns the org you’re targeting.
  3. Slug format correct? Hex in the URL, original in bodies/queries/docpaths.
  4. Resources in the same org? Workspaces and documents must share the org in the URL.
  5. Required fields present? Check the endpoint’s schema.