Skip to Content

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/ready

The 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

FailureMeaningResponse
model_not_entitledNo matching usage grantCheck the selected product, model and rules
product_not_configuredRequired account/default product/pricing is missingRepair configuration; waiting alone does not fix it
rate_limitedA rate rule rejects admissionRead Retry-After; an oversized request may have no delay
usage_limit_exhaustedProduct allowance exhaustedRenew/change the grant rather than retrying unchanged
too_many_concurrent_requestsA simultaneous-request slot is unavailableWait for work to finish or cancel unwanted work
metering_unavailableCounter store, lease or metering dependency failedTreat as service failure, not provider exhaustion
stream_authorization_unavailableCurrent access could not be verified during streamingStop displaying new output; retry only after access/service recovery
customer_deleted, customer_access_revoked, customer_suspendedCustomer access ended or is suspendedFollow 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.

Last updated on