Gateway

Gateway configuration

How a request is shaped on the way through Cran: routing headers, the compiled routing policy, caching, reliability knobs, guardrails, and budgets.

Request headers

x-cran-configworkflow-slug

Select a published workflow architecture for this request (alias for slug routing).

x-cran-routecost

Route via the architecture’s cost route when one is defined.

x-cran-context-tokensnumber

Hint used by conditional long-context routing rules.

x-cran-metadatajson

Attach cost-attribution metadata to the usage event for this call.

x-cran-no-storeboolean

Zero-retention mode - meter usage but persist no prompt/response content.

Routing policy

A published architecture compiles into a routing policy the gateway executes per call:

Primary - the default model (highest measured quality from the audit).
Fallback chain - tried in order when the primary errors.
Cost route - an optional cheaper model selected via x-cran-route: cost.
Conditions - per-class rules (e.g. long-context inputs route to a wide-context model).

Architecture parameters

cache_ttl_secnumber

Exact-match response cache TTL in seconds. 0 disables caching.

request_timeout_msnumber

Per-request timeout. Default 120000.

max_input_tokensnumber

Input guardrail - requests exceeding this are rejected before dispatch.

Reliability

Retries use jittered exponential backoff and honor the provider’s Retry-After header (capped at 20s) on 429/5xx. A per-model circuit breaker pulls a repeatedly-failing model out of rotation briefly, and the fallback chain covers the rest. These apply to every modality.

Guardrails

Input and output guardrails run around each call: a maximum input-token check, optional JSON-object enforcement (when response_format is json_object), and PII checks on persisted traffic. A blocked request returns 400 with a guardrail_denied type.

Budgets & rate limits

Per-project budgets (daily / monthly spend caps) and rate limits (requests-per-minute, tokens-per-minute) are enforced before the provider call, fail-closed on a limits-service error. Over-budget returns 402; over-rate returns 429 with a Retry-After header.

bash

# example: a rate-limited response
HTTP/1.1 429 Too Many Requests
retry-after: 60
{ "error": { "type": "rate_limit_exceeded", "message": "…" } }