Gateway operations
Capture x-request-id, the operation, HTTP status and normalized error code when diagnosing a failure. Never include access tokens, provider credentials or raw authorization headers. Use admin logs for server-side streaming logs and usage and request history for recorded outcomes.
Health and readiness
curl https://gateway.preternatural.ai/
curl https://gateway.preternatural.ai/health
curl https://gateway.preternatural.ai/readyThe root identifies the service. /health returns 200 with Redis/database status even when a dependency is not ready; it proves liveness, not readiness to serve inference. /ready returns 200 only when Redis, the database, schema and stream authorization are ready, otherwise 503. Use readiness for deployment/traffic decisions. Neither endpoint proves a particular provider account, product or model can serve a request.
Diagnose the layer
| Failure | Meaning | Response |
|---|---|---|
model_not_entitled | No matching usage grant | Check the selected product, model and rules |
product_not_configured | Required account/default product/pricing is missing | Repair configuration; waiting alone does not fix it |
rate_limited | A rate rule rejects admission | Read Retry-After; an oversized request may have no delay |
usage_limit_exhausted | Product allowance exhausted | Renew/change the grant rather than retrying unchanged |
too_many_concurrent_requests | A simultaneous-request slot is unavailable | Wait for work to finish or cancel unwanted work |
metering_unavailable | Counter store, lease or metering dependency failed | Treat as service failure, not provider exhaustion |
stream_authorization_unavailable | Current access could not be verified during streaming | Stop displaying new output; retry only after access/service recovery |
customer_deleted, customer_access_revoked, customer_suspended | Customer access ended or is suspended | Follow the session state and explain the account condition |
The gateway can also return service_unavailable while shutting down. Its one-second retry hint is an admission/service instruction; it does not make an ambiguously delivered generation safe to repeat.
Interrupted streams
A stream can end because the caller cancelled, the session changed, access ended, a deadline elapsed, capacity ownership was lost or a provider/network failed. Preserve output already delivered and mark an incomplete answer as incomplete.
When the gateway terminates a stream, the terminal SSE event can contain an error rather than [DONE]. Ordinary customer streams recheck authoritative access during delivery. A lookup outage is reported as stream_authorization_unavailable, not falsely as customer revocation. Client SDK error handling distinguishes session and API errors.
Do not automatically replay a request after partial output or an unknown network outcome. The provider may already have generated and consumed quota. Subscription fallback after a confirmed pre-generation refusal is a separate gateway policy; it does not authorize arbitrary client retries.
Local operation
Use the Localnet service URLs for your checkout, rather than fixed ports. The SDK’s local presets and explicit URL overrides are described in configuration. Check readiness before testing a request; do not confuse a reachable static docs site with a healthy Modem gateway.