gateway api

Errors

Errors that originate at the gateway use one envelope with a closed set of types. Errors that originate upstream pass through in the provider's own format — so your existing provider error handling keeps working.

The error envelope

shape

{
  "type": "authentication_error",
  "message": "API key is missing or malformed.",
  "request_id": "0190a7c2-7e11-7cc3-a312-9f1b22d40e88"
}

request_id matches the x-understudy-request-id response header — include it when reporting an issue.

Error types

type	status	when
`authentication_error`	401	The sk_* key is missing, malformed, revoked, or unknown.
`authorization_error`	403	The key is valid but not allowed to touch the referenced resource — usually a cross-organization reference.
`invalid_request_error`	400 / 422	The request can't be honored as expressed: malformed tags, an unknown project or workload, an unknown catalog model, or a BYO key on a routed workload.
`rate_limit_error`	429	Gateway-level rate limiting. Upstream provider 429s pass through in the provider's own format instead.
`internal_error`	500	Something failed inside the gateway. The request_id is the handle for investigation.

Upstream errors

When the upstream provider returns an error on passthrough traffic, the gateway passes it through — status, body, and format — exactly as if you had called the provider directly. On routed traffic, a failing upstream (5xx, 429, timeout) triggers a fallback retry against your primary provider before you ever see an error; the response reports x-understudy-route: fallback.