How it works
What happens to a request
Gatewayz is a thin, strict layer between your agent and the model providers. Here is every step a request takes, and the rules each step keeps.
The request path
- 1
Authenticate the key
The request's API key is checked first. A key that's supplied but invalid gets
401; it's never quietly served as an anonymous request. - 2
Apply limits
Rate limits are checked before anything is counted against the key. Then the key's request cap and the account's credit balance: if either is spent, the request stops here with a
402and a code that says which. - 3
Resolve the model — exactly
An undated alias like
claude-sonnet-4-6resolves to its exact snapshot. An id that isn't in the catalog gets400 model_not_found. There is no "closest match": we never send your request to a model you didn't name. - 4
Route to a provider serving that model
The router ranks the providers that offer the requested model and sends the request to the first healthy one. A circuit breaker takes a failing provider out of rotation, and the next provider for the same model is tried. Status: built and wired in; not yet proven on live traffic.
- 5
Stream the response back
OpenAI-compatible responses on
/v1/chat/completions, native Anthropic Messages events on/v1/messages. If the provider fails partway through a stream, the stream ends with an explicit error event rather than just stopping. - 6
Meter and bill
Tokens are billed as the provider reports them, at list price plus a routing fee. If a request fails over to a provider that charges more for the same model, you're billed at the higher of the two rates, never below the rate the model is advertised at.
The error contract
Agents act on status codes, not error messages. Every failure below tells a program whether retrying can help. The ones that can't never come back as a status an SDK retries automatically.
| Status | Code | Meaning | Retry? |
|---|---|---|---|
| 400 | model_not_found | The model id isn't in the catalog. | No. Fix the id. |
| 401 | invalid_api_key | The key isn't recognised. | No. Fix the key. |
| 402 | insufficient_credits | The account balance is empty. | No. Top up, then retry. |
| 402 | request_cap_exhausted | This key's request cap is spent. | No. Raise the cap or use another key. |
| 429 | — | Rate limited, here or at the provider. | Yes, with backoff. |
| 5xx | — | A server or upstream fault. | Yes, with backoff. |
Why this matters: who reads the error?
What we never do
- Substitute a model. Resolution only — see resolution, not substitution.
- Store prompt or response content for API calls. What we keep, and for how long, is on Security & data.
- Run a model of our own, so there's nothing to steer you toward.
Every build identifies itself
GET https://api.gatewayz.ai/health/quick returns the commit serving the request, so a deploy can be confirmed from outside. The status page shows it live.
Make your first call
One key, OpenAI-compatible or native Anthropic Messages.