Skip to main content
When something goes wrong, Lithtrix returns a consistent error envelope so your agent can handle failures programmatically without parsing free-form messages. Every error response uses the same three-field structure, regardless of the type of error.

​
Error envelope format

{
  "status": "error",
  "error_code": "MACHINE_READABLE_CODE",
  "message": "Human-readable description."
}
Always check status first in your response parsing. If status is "error", read error_code to determine the appropriate action. Do not rely on message text in code — it may change.

​
Error code reference

CodeHTTP statusDescription
INVALID_API_KEY401Key missing or not recognised
RATE_LIMIT_EXCEEDED429Per-minute limit hit — check Retry-After header
OVER_LIMIT—Lifetime cap reached (in usage object, not HTTP error)
AGENT_ALREADY_EXISTS409Name + owner pair already registered
UPSTREAM_ERROR502Upstream search provider error
SERVICE_UNAVAILABLE503Circuit breaker open

​
How to handle each error

Your API key is missing from the request or is not recognised. This is returned when the Authorization header is absent, malformed, or contains a key that does not exist in the system.What to do:
  • Confirm the Authorization header is present and formatted as Bearer ltx_your_key.
  • Check that the key has not been rotated. If you recently called POST /v1/keys/rotate, the old key is immediately invalidated.
  • If you do not have a key, register your agent via POST /v1/register to obtain one.
Your agent has exceeded the per-minute request limit for your tier (60/min on Free, 600/min on Pro).What to do:
  • Read the Retry-After response header. It contains the number of seconds to wait before retrying.
  • Implement exponential backoff if you are hitting this limit repeatedly.
  • If your agent’s workload regularly exceeds 60 requests per minute, upgrade to the Pro tier.
The Free tier lifetime cap of 300 calls has been reached. Unlike other errors, OVER_LIMIT does not produce an HTTP error status. The search response returns normally with HTTP 200, but over_limit is set to true in the usage object.What to do:
  • Check usage.over_limit in every search response if you are on the Free tier.
  • When over_limit is true, follow the upgrade_url value in the usage object to initiate a Pro upgrade.
  • Calls made after the cap is reached still return results, but you should prompt your users to upgrade to avoid interruption.
The combination of agent_name and owner_identifier you sent to POST /v1/register is already registered in the system.What to do:
  • If you already have a key for this agent, retrieve it from wherever you stored it at registration time. Keys are shown only once.
  • If you have lost the key, rotate it via POST /v1/keys/rotate using your existing key, or contact support.
  • If you want to register a new agent, use a different agent_name or owner_identifier.
The upstream search provider returned an error or did not respond in time. This is a transient condition — the Lithtrix service itself is healthy.What to do:
  • Retry the request after a short delay (start with 1–2 seconds).
  • Use exponential backoff if retries continue to fail.
  • If the error persists for more than a few minutes, check the Lithtrix status page for upstream incident reports.
The circuit breaker is open. Lithtrix has detected repeated upstream failures and is temporarily blocking requests to protect system stability.What to do:
  • Do not retry immediately. Wait at least 30 seconds before attempting another request.
  • The circuit breaker closes automatically once the upstream recovers.
  • Monitor the Lithtrix status page for resolution updates.