Errors and rate limits

Every non-2xx response from every Luigi’s Box AI endpoint has the same body.

The error body

{
  "reason": "Invalid filter expression.",
  "exception_details": {},
  "request_id": "01JQ8H3Z9K2F7M4N6P8R0S2T4V"
}

Field	Meaning
reason	A human-readable, actionable message. Show it to a developer, not to a shopper.
exception_details	Machine-readable context. {} when there is nothing to add.
request_id	Correlation ID, matching the X-Request-Id response header.

Log request_id. Luigi’s Box support uses it to find the request.

Validation failures

When the problem is a specific value, exception_details.validation_errors lists every field-level problem in the request:

{
  "reason": "Request validation failed",
  "exception_details": {
    "validation_errors": [
      {
        "loc": ["query", "size"],
        "msg": "Input should be less than or equal to 100",
        "type": "less_than_equal"
      },
      {
        "loc": ["body", "objects", 0, "@id"],
        "msg": "Field required",
        "type": "missing"
      }
    ]
  },
  "request_id": "01JQ8H3Z9K2F7M4N6P8R0S2T4V"
}

• loc is the path to the offending value from the request root.
• type is a stable machine code — safe to branch on.
• msg explains the problem in words — safe to log, not to branch on.

Status codes

Status	Meaning	What to do
400	Malformed request — unparseable body, bad encoding	Fix the request; do not retry
401	Missing, expired or wrong-audience token	Get a fresh token and retry once
403	Authenticated, but not permitted on this resource	Check the permission and the resource you named
404	Not found — or not visible to your credentials	See the note below
409	Conflict with the resource’s current state	Re-read the resource and retry with what you find
422	Validation failed	Read validation_errors; do not retry unchanged
429	Rate limit exceeded	Back off — see below
502	An upstream step failed	Retry with backoff
503	Temporarily unavailable	Retry with backoff

403 and 404 are both authorization answers

A 403 means your credentials hold some grant on the resource but not the one this call needs. A 404 on a single resource means they hold no grant on it at all — the API does not confirm that something exists to a caller who cannot see it. A 404 on a resource you expect to exist can therefore be a permissions problem rather than a wrong ID.

Collection endpoints always answer 403 rather than 404, because you named the scope yourself. On a listing that takes organization_id, that parameter is the scope: send it and credentials granted on that organization are enough, omit it and the listing spans every organization, which takes a grant that wide.

Which failures are worth retrying

Retry	Do not retry
429, after the interval it tells you	400, 422 — the request itself is wrong
502, 503, with exponential backoff	403, 404 — permissions do not change on retry
401, exactly once, with a new token	409 without re-reading the resource first

Add jitter to the backoff, so that a fleet of workers does not retry at the same instant.

Rate limits

Rate-limited endpoints report your budget on every response, not only on a 429:

Header	Meaning
RateLimit-Limit	Requests allowed in the current window
RateLimit-Remaining	Requests left in it
RateLimit-Reset	Seconds until the window resets

Exceeding the limit gives you 429 with the standard error body and a Retry-After header in seconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 42

Honour Retry-After. It is an upper bound on the wait; a client that respects it does not retry into the same window.

RateLimit-Remaining on successful responses shows a job approaching its budget before it starts receiving 429.

If the limits do not fit your traffic, contact Luigi’s Box — they are set per account and can be raised.

Refused traffic

A 403 that is not about permissions is usually bot control — most often a server-side integration attempting the browser token flow, or a page origin that was never registered for its publishable key.

Debug output

Some discovery responses can carry a debug object describing ranking decisions. It is gated on a permission granted only to Luigi’s Box staff, and its contents carry no compatibility guarantee. Passing debug=true without that permission is ignored.

See also

• Requests and responses
• Authentication overview — audiences and permissions
• Feed troubleshooting — ingestion-specific problems