Skip to main content

Error response shape

All gateway errors return JSON with a consistent structure:
string
Machine-readable error code. Use this to branch your error handling logic.
string
Human-readable description of what went wrong.
string
The unique gateway request ID. Use this to find the request in the Gatelit dashboard logs.
Successful responses also include the request ID in the x-gatelit-request-id response header. Save it alongside any response you store so you can look up the full logs later.

Error codes

unauthorized — 401

The request could not be authenticated. Common causes:
  • The token has expired (signed tokens default to a 60-second TTL).
  • The token signature is invalid — check that you are signing with the correct secret.
  • The Authorization header is missing or malformed.
  • A GatelitKey has been revoked.
Resolution: Ensure your getToken implementation fetches a fresh token before each request and that the signing secret matches the one configured in the dashboard.

gateway_error — 400

The request was malformed or contained invalid data. Common causes:
  • Request body is not valid JSON.
  • The model field is missing or not in "provider/model-name" format.
  • A required prompt variable was not supplied when calling /v1/prompts/:id/run.
  • An invalid value was provided for a typed prompt variable (e.g. passing "hello" for a number variable).

gateway_error — 404

The requested resource does not exist. Common causes:
  • The prompt ID in /v1/prompts/:id/run does not match any prompt in your organisation.
  • The prompt exists but has no published version — only published versions are executed.
  • The request path is not a recognised gateway route.

provider_error — 4xx / 502

The upstream LLM provider returned an error. The gateway forwards the provider’s HTTP status and error message directly. Common causes:
  • The provider rate-limited the request (429).
  • The requested model is not available or the provider account lacks access.
  • The input exceeded the model’s context window.
  • The provider’s API is temporarily unavailable (502).
Resolution: Inspect message for the provider’s original error text. Configure a fallback chain to automatically retry on rate_limit or provider_error triggers.

invalid_json — client-side

Thrown by the JS SDK’s chatJson() method, not by the gateway itself. Indicates the model returned a response that could not be parsed as JSON, despite an outputSchema being set. Resolution: Retry the request. If the problem persists, use a more capable model or tighten the system prompt to reinforce the JSON output requirement.

Handling errors in code

Use the GatelitError class from @gatelit/sdk to distinguish gateway errors from other exceptions. It exposes code, message, and status.

In the Vue SDK

When using useGatelit, errors are captured in the error ref rather than thrown. Check it reactively:
The error ref is reset to null at the start of the next send() call, and also when you call clear().

Locating requests in the dashboard

Every request — successful or failed — is assigned a requestId. You can find it in:
  • The x-gatelit-request-id response header on successful requests.
  • The requestId field in the error response body on failed requests.
  • The meta.requestId property on ChatResponse objects returned by the JS SDK.
Use this ID in the Logs section of the Gatelit dashboard to view the full request details, token usage, latency, model used, and any upstream provider errors.