For the complete documentation index, see llms.txt. This page is also available as Markdown.

Error Codes

Error codes returned by the Luciq Query API, what each one means, and whether to fix the request or back off and retry it later.

Error Codes

Every error has the same structure:

{ "error": { "code": "invalid_request", "message": "…", "query_id": "…", "details": { } } }

Error codes are never renamed or reused, so you can safely branch on them in code.

Code
HTTP
Retry?
What to Do

invalid_request

400

No

Fix the query. message and details explain what is wrong, often with a did_you_mean.

unauthorized

401

No

The key is missing, unknown, revoked, or expired. details.reason tells you which.

forbidden

403

No

The key does not cover this app, entity, or level, or your plan does not include the feature.

not_found

404

No

The entity does not exist. Check /v1/entities.

budget_exceeded

422

Change the query

The query is valid but too expensive to run. Narrow the time range, group by fewer columns, or add filters. details.cap names the limit hit.

rate_limited

429

Back off

Wait for Retry-After.

internal

500

Back off

Temporary. If it continues, contact support with the query_id. It is in error.query_id and the X-Query-Id header.

upstream_failure

502

Back off

Temporary. Retry with exponential backoff.

timeout

504

Once

Retry once. If it repeats, narrow the query.

On a 429, details.reason tells you which limit you hit: rate_limit or concurrency. By default, you can send 60 requests per minute and 1,000 per hour. An app runs up to 8 queries at once.

Error reasons

Some errors carry details.reason, which tells you the exact cause.

Status

code

details.reason

Meaning and action

401

unauthorized

unknown

The key doesn't exist. Check for typos.

401

unauthorized

revoked

The key was revoked. Create a new one.

401

unauthorized

key_expired

The key has expired. Create a new one.

403

forbidden

app_not_allowed

The key's scope doesn't include this app, or the slug is wrong.

403

forbidden

plan_disabled

The Query API is turned off for this app or company.

429

rate_limited

rate_limit

Per-minute or per-hour limit. Wait Retry-After.

429

rate_limited

concurrency

Too many queries at once. Wait Retry-After.

Last updated