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.
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