Back to home

Guide

Gateway Docs

Virouter sits between your application and upstream providers. It validates auth, enforces rate limits, parses the model id, forwards the request, and charges Token quota based on real returned token usage.

Request lifecycle

  1. Validate the Virouter virtual API key from the Authorization header.
  2. Apply rate limits per API key and per IP, with a separate burst window for spikes.
  3. Parse model from the JSON body and reject unconfigured ids.
  4. Run a max-cost preflight against the wallet to avoid forwarding requests that cannot be charged.
  5. Forward to the configured upstream endpoint with the gateway's server-side credentials.
  6. Read returned token usage and atomically decrement the wallet using a conditional update.
  7. Return billing headers and log the request for visibility on the analytics page.

Idempotency

Pass an Idempotency-Key header to make a request retry-safe. The gateway records the first body and replays the original response with x-virouter-idempotency-replay: 1 when a retry arrives with the same key and body. Sending the same key with a different body returns 409.

Error codes

401

API key is missing, invalid, revoked, or not active.

402

Insufficient Token quota in the wallet for the requested call.

409

Idempotency key reused with a different body, or processing in progress.

429

Rate limit reached. Wait for the reset window before retrying.

503

Upstream gateway capacity is temporarily unavailable. Retry later.

Security reminder

Never hardcode your Virouter key in frontend code. Store it in environment variables, CI secrets, or a managed secrets provider. Share only masked key prefixes with support.