Widget API errors

Every rejected widget query returns the same JSON shape, whatever went wrong. Read the code, not the message: the code is stable and the wording is not. The partner API has its own list, on The Elie API.

The error body

{
  "error": {
    "code": "schema_invalid",
    "message": "question must not be blank",
    "correlation_id": "9f3c..."
  }
}

correlation_id is present when you send one, as X-Correlation-Id or X-Request-Id. Send one per request and log it: it is what lets us find your call in our logs. A 401 never carries it. A details list appears only when a request fails field-level validation.

Codes

Status	code	What happened	Retry?
401	access_denied	No token, or one that is unknown, expired, or presented from a domain it does not allow.	No. Issue a new token
403	access_denied	The token is valid, but not for this knowledge base.	No
402	billing_denied	The workspace has no credit left.	No. Top up first
422	schema_invalid	question is missing or blank.	No
503	kb_reindexing	The knowledge base is rebuilding its index and cannot answer yet.	Yes
503	dependency_unavailable	A service behind the answer is down, slow, or too busy to take another stream.	Yes
503	service_auth_unavailable	Internal authentication is unavailable for a moment.	Yes
500	internal_error	An unhandled fault on our side, including a request body that is not valid JSON, which is not reported as a validation error.	Once, then report it

Wait between retries rather than repeating at once: a retryable code means the condition is expected to clear, not that it has. A request body over 1 MB is refused before it reaches Elie, with a plain web page rather than this JSON.

The three you will actually hit

401 within an hour of it working. The token expired. Tokens last 60 minutes by default; see Developer access and widget tokens.

401 from a browser but not from curl. The page's address is not on the token's list of domains. A call from your own server sends no Origin header and is accepted; a browser one must match exactly, scheme and port included, so https://app.example.com does not cover http://app.example.com. If the browser reports a CORS failure with no status at all, the domain is missing from the knowledge base's Allowed origins (CORS) list instead.

503 kb_reindexing. Someone changed the knowledge base's embedding settings and it is rebuilding. Nothing is wrong; questions are answered again when it finishes.

Not an error

A 200 with abstained: true means Elie found no evidence good enough to answer from. Show the message to the reader; asking the same question again gives the same result.

Next

• Query endpoints - the calls these codes come from.
• Troubleshooting - symptoms across the whole product.