Errors & rate limits

All API errors return a consistent JSON shape with a stable code, human-readable message, and request_id for support.

Error format

Failed requests return HTTP 4xx/5xx with this body:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'message' is required.",
    "request_id": "req_abc123def456"
  }
}

Request tracing

Every response includes an X-Request-Id header. You may pass your own X-Request-Id (8–64 alphanumeric characters) and we will echo it back. Include request_id when contacting support.

Rate limits

Authenticated endpoints return rate-limit headers on success and 429 responses when limits are exceeded.

Retry-After: Seconds to wait before retrying
X-RateLimit-Remaining-Minute: Remaining requests in the current minute
X-RateLimit-Remaining-Day: Remaining requests for the current UTC day

Error codes

Code	HTTP	Description
MISSING_API_KEY	401	No API key was provided in the Authorization or X-API-Key header.
INVALID_API_KEY_FORMAT	401	The API key does not match the expected tlh_live_* format.
INVALID_API_KEY	401	The API key is unknown or incorrect.
API_KEY_REVOKED	401	The API key has been revoked and can no longer be used.
RATE_LIMIT_EXCEEDED	429	Too many requests in the current minute. Retry after the Retry-After header value.
DAILY_QUOTA_EXCEEDED	429	The daily request quota for this API key has been reached.
INVALID_JSON	400	The request body is not valid JSON.
INVALID_REQUEST_BODY	400	The request body must be a JSON object.
VALIDATION_ERROR	400	One or more request fields failed validation.
NOT_FOUND	404	The requested resource was not found.
UPSTREAM_ERROR	502	An upstream AI provider failed while generating a response.
INTERNAL_ERROR	500	An unexpected server error occurred.