Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lumiqtrace.com/llms.txt

Use this file to discover all available pages before exploring further.

All LumiqTrace API errors return a JSON body with a single error field containing a human-readable message. HTTP status codes follow standard conventions — your client should branch on the status code, not the error string, since messages may change without notice.

​
HTTP Error Codes

​
400 Bad Request

The request body or parameters are invalid. Fix the request before retrying — retrying without changes will produce the same error. 
{
  "error": "Max 100 events per batch"
}
Common causes:
  • Sending more than 100 events in a single POST /v1/ingest call.
  • A required query parameter (such as projectId) is missing.
  • A field value does not match the expected type or format.

​
401 Unauthorized

Your request is missing credentials or the credentials provided are invalid or expired. 
{
  "error": "Invalid API key"
}
Check that:
  • You included the correct header (x-api-key for ingest, Authorization: Bearer ... for data endpoints).
  • Your API key has not been revoked from Settings → API Keys.
  • Your session token has not expired.

​
403 Forbidden

Your credentials are valid but you do not have permission to access the requested resource. 
{
  "error": "Not a member of this organization"
}
This typically means your account does not belong to the organization that owns the project you are requesting. Contact your organization owner to request access.

​
429 Too Many Requests

You have exceeded a rate limit. The response includes a Retry-After header indicating the number of seconds to wait before retrying. 
{
  "error": "Rate limit exceeded"
}
Two distinct 429 causes — read the error message to distinguish them:
Error messageCauseResolution
"Rate limit exceeded"Per-minute request rate limit hitWait for Retry-After seconds, then retry
"Monthly quota exceeded"Organization has used all events for this billing periodUpgrade plan, reduce sampleRate, or wait for quota reset
A 429 with "Monthly quota exceeded" on POST /v1/ingest will not resolve by retrying later in the same month. The only resolutions are upgrading your plan, reducing your SDK sampleRate to stay within quota, or waiting until the quota resets at the start of next month. Do not retry these in a loop — they will keep failing.

​
500 Internal Server Error

An unexpected error occurred on the LumiqTrace servers. This is not caused by your request. Retry with exponential backoff — most transient errors resolve within a few seconds. 
{
  "error": "Internal server error"
}

​
Rate Limits

Endpoint groupLimit
POST /v1/ingest1,000 requests/minute per API key
Dashboard endpoints (data, metrics)300 requests/minute per session
AI endpoints (/v1/ai/*)20 requests/hour per organization
Rate limits are enforced using a sliding window algorithm. If you hit the ingest rate limit frequently, consider batching more events per request (up to the 100-event maximum) to reduce request count.

​
Retry Guidance

  • 400: Do not retry without fixing the request.
  • 401 / 403: Do not retry — fix credentials or permissions first.
  • 429: Wait for the number of seconds specified in the Retry-After response header, then retry.
  • 500: Retry with exponential backoff starting at 1 second. If errors persist beyond a few minutes, check the LumiqTrace status page.