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.
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
Authorizationheader is missing or malformed. - A
GatelitKeyhas been revoked.
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
modelfield 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 anumbervariable).
gateway_error — 404
The requested resource does not exist.
Common causes:
- The prompt ID in
/v1/prompts/:id/rundoes 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).
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 theGatelitError class from @gatelit/sdk to distinguish gateway errors from other exceptions. It exposes code, message, and status.
In the Vue SDK
When usinguseGatelit, errors are captured in the error ref rather than thrown. Check it reactively:
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 arequestId. You can find it in:
- The
x-gatelit-request-idresponse header on successful requests. - The
requestIdfield in the error response body on failed requests. - The
meta.requestIdproperty onChatResponseobjects returned by the JS SDK.