Common issues
FAQs from real tickets.
If none of these fit, email support@aigateway.sh and include the X-Request-Id from your failed call.
My request returned 402 budget_exceeded.
The sub-account's monthly spend cap was reached. Raise it with PATCH /v1/sub-accounts/:id or wait for the month to roll over. Enforcement runs before dispatch, so you are never charged for the blocked request.
A model I used yesterday is gone today.
We prune models that labs deprecate upstream and email paid accounts ahead of time. If you want stability, pin to a full version tag (e.g. anthropic/claude-sonnet-4.6) instead of the floating name.
Streaming stops mid-response.
Keep-alives should arrive every 15s. If you see a hang, check your proxy buffer settings (nginx proxy_buffering off;) and make sure your client isn't wrapping the body with a gzip layer that never flushes.
OpenAI SDK error: model not found.
Make sure you're pointing at https://api.aigateway.sh/v1 (not /v1/chat). The model ID uses the provider/name format — openai/gpt-5.4, not gpt-5.4.
How do I bring my own provider API key?
Paid accounts can enable BYOK on the dashboard. Per-request, send the key as x-byok-<provider> header. We still meter at 5%.
Can I get a dedicated endpoint?
Enterprise accounts get a dedicated hostname with IP allow-listing and private audit log export. Email enterprise@aigateway.sh.
Should I use aigateway-py / aigateway-js, or just the OpenAI SDK?
For chat, embeddings, images, STT, TTS, moderations — use the OpenAI SDK with base_url='https://api.aigateway.sh/v1'. We're a drop-in. Reach for the AIgateway SDK only when you need the aggregator-native primitives OpenAI doesn't model: async jobs (video/music/3D), sub-accounts, evals, replays, signed file URLs, or webhook signature verification.
Can I use aigateway-cli in CI?
Yes. Pass --key directly or set AIGATEWAY_API_KEY in env, then call commands non-interactively. `aig models --json`, `aig sub-account create`, `aig eval run`, `aig usage --json`, and `aig replay` are all CI-friendly. For first-run setup without prompts: `AIGATEWAY_API_KEY=sk-aig-... aig init --no-scaffold`.
My MCP client can't reach mcp.aigateway.sh.
That subdomain doesn't exist — the MCP server lives at api.aigateway.sh/mcp (Streamable HTTP, preferred) or api.aigateway.sh/mcp/sse (legacy). Inspect tools in browser at api.aigateway.sh/mcp/inspect.