FAQ

Self-serve answers to the top developer questions.

Rate limits, auth, timeouts, model selection, and the most common SDK errors — with copyable curl and code snippets so you can paste-fix without filing a ticket.

I’m getting HTTP 429 — what is my rate limit?

Every response includes rate-limit headers so your client can back off cleanly before hitting the cap. NorthGate enforces per-key limits by tier:

  • Developer (free): 100 requests / day
  • Team ($49/mo): 10,000 requests / month
  • Enterprise: configurable, defaults to 100,000 requests / month (override with the ENTERPRISE_RATE_LIMIT env var)

When you exhaust your quota the response carries 429, a body of {"error":{"type":"rate_limit_exceeded","code":"rate_limit_exceeded"}}, and the same rate-limit headers. Retry after the Retry-After value (seconds).

curl -i -X POST https://northgate-ai.polsia.app/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ngt_your_api_key" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}' # Response headers: # HTTP/1.1 200 OK # X-RateLimit-Limit: 100 # X-RateLimit-Remaining: 99 # X-RateLimit-Reset: 1718823600 # X-RateLimit-Window: day
How do I rotate / regenerate my API key?

Visit /dashboard/api-keys, click Regenerate, and confirm. Your old key is invalidated the moment the new one is minted — any service still using the old key will start receiving 401 Unauthorized.

The new key is shown once via a 5-minute signed-token reveal; copy it then. If you lose it, regenerate again.

# Programmatic regeneration (session-auth required): curl -X POST https://northgate-ai.polsia.app/auth/key/regenerate-session \ -H "Cookie: ng_session=" # Response: # { "ok": true, "revealToken": "" }
My request times out. How long does NorthGate wait?

NorthGate sets a hard upstream timeout per request: 60s for chat completions and 30s for embeddings. If the upstream provider is slower than that, the gateway falls through to the next provider in the route chain, then surfaces a 502 if every provider in the chain gave up.

Set your client-side timeout to at least 90s to absorb retries. For long-context requests, chunk the prompt (e.g. summarize section by section) and call the gateway repeatedly — the routing fallback makes this cheap.

Which model should I pick?

If you don’t specify a model, the gateway picks one based on your ?route= strategy — the default balanced route is fine for most cases. Override per request with a query string:

  • ?route=cheapest — Together AI → Groq → Fireworks AI → OpenAI → Anthropic (best for high-volume batch jobs)
  • ?route=fastest — Groq → Fireworks AI → Together AI → OpenAI → Anthropic (best for real-time UIs)
  • ?route=balanced — Together AI → Fireworks AI → Groq → OpenAI → Anthropic (general purpose, the default)
  • ?route=best_quality — Together AI → Fireworks AI → Anthropic → OpenAI → Groq (highest output quality, slower and pricier)

If you do request a specific model, NorthGate routes it to the right hosting provider first — Qwen / GLM / DeepSeek prefer Together AI, fireworks/* prefers Fireworks AI, groq/* prefers Groq.

curl -X POST "https://northgate-ai.polsia.app/v1/chat/completions?route=fastest" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ngt_your_api_key" \ -d '{"model":"llama-3.3-70b-versatile","messages":[{"role":"user","content":"hi"}]}'
Does NorthGate support webhooks?

Not yet — there’s no outbound webhook infrastructure today, so we don’t push async events when a request finishes or when a quota edge approaches. We’re tracking webhook delivery for a future release.

In the meantime, every request is durable in request_logs. Query it via GET /usage with your API key — the developer tier returns today’s aggregates, team/enterprise tiers return the current calendar month:

curl https://northgate-ai.polsia.app/usage?period=day \ -H "Authorization: Bearer ngt_your_api_key" # Response: { "period": {...}, "totals": {...}, "by_model": [...] }
How do I authenticate with the SDK?

Both the Python and Node SDKs wrap the same OpenAI-compatible surface. Pass your key to the client constructor and point it at the NorthGate base URL. Five lines:

# Python from northgate import NorthgateClient client = NorthgateClient( api_key="ngt_your_api_key", base_url="https://northgate-ai.polsia.app/v1", route="balanced") resp = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello"}]) print(resp["choices"][0]["message"]["content"])
// Node.js const { NorthgateClient } = require("northgate-sdk"); const client = new NorthgateClient({ apiKey: "ngt_your_api_key", baseUrl: "https://northgate-ai.polsia.app/v1", route: "balanced" }); const r = await client.chat.completions.create({ model: "gpt-4o-mini", messages: [{ role: "user", content: "Hello" }] }); console.log(r.choices[0].message.content);
I’m getting 401 Unauthorized — what’s wrong?

Walk this checklist in order:

  • Missing header: every gateway call needs an Authorization: Bearer <key> header (or X-API-Key — both work).
  • Old key after regeneration: if you (or anyone with dashboard access) regenerated the key, the previous one is immediately invalid. Pull the new one from /dashboard/api-keys.
  • Whitespace in the key: keys start with ngt_. Trim spaces, tabs, or stray line breaks from the env var or secret file before pasting.
  • BYOK mode: if you set X-API-Key to a key that isn’t a NorthGate-issued key (i.e. you’re forwarding your own OpenAI / Anthropic key), NorthGate treats it as a BYOK passthrough and expects you to pass through X-Provider-Base-URL too — not a 401 case, but easy to confuse with one.
  • Wrong endpoint: /v1/chat/completions, not /v1/ or /chat/completions. The base URL is https://northgate-ai.polsia.app/v1.
My request returns 413 Payload Too Large.

NorthGate caps a single request body at 100,000 characters across all message.content fields combined. Exceed it and the gateway returns 413 with body {"error":{"type":"request_too_large"}}.

Workarounds:

  • Chunk long contexts into smaller per-section calls and stitch the results.
  • Switch to /v1/embeddings for retrieval-augmented flows — embed once, retrieve the relevant chunks per query.
  • Use the SDKs’ built-in streaming for any response longer than a few hundred tokens.
How do I see usage / logs for my account?

Three places, each for a different audience:

  • GET /usage — programmatic, returns totals + by-model breakdown for the current period (developer = today, team/enterprise = current month). Authenticate with your API key.
  • /dashboard/analytics — session-auth web view of the last 30 days, with funnel (visits → signup → first API call → repeat) and top models.
  • /dashboard — session-auth overview, current-period usage against your tier limit, masked API key, and billing date.
curl https://northgate-ai.polsia.app/usage \ -H "Authorization: Bearer ngt_your_api_key"
Does NorthGate log my prompts?

No. Raw prompts and completions are never persisted. The PIPEDA-aligned audit_logs records a request fingerprint — model, provider, token counts, latency, route strategy, status, and a SHA-256 hash of the client IP (the raw IP is never stored). Retention is 2 years; data lives in Neon PostgreSQL (US-East-2) for Canadian data residency.

# Confirm what's actually available right now (model catalog): curl https://northgate-ai.polsia.app/v1/models \ -H "Authorization: Bearer ngt_your_api_key"
My SDK can’t connect — SSL / base URL / proxy issues.

Walk this:

  • Base URL: the OpenAI SDK / LangChain / LiteLLM should point to https://northgate-ai.polsia.app/v1 (the trailing /v1 matters — the SDK adds /chat/completions on top).
  • OpenAI SDK override: new OpenAI({ apiKey, baseURL: "https://northgate-ai.polsia.app/v1" }) — not https://api.openai.com/v1/.
  • Corporate proxy: allow egress to northgate-ai.polsia.app on 443. NorthGate terminates TLS upstream, so a proxy must not MITM that host.
  • OpenSSL / CA bundle: if you’re on a corporate machine with a custom CA, make sure NODE_EXTRA_CA_CERTS (Node) or REQUESTS_CA_BUNDLE (Python) is set to your IT-issued bundle. NorthGate’s cert chain is signed by public CAs and is trusted by default.
  • DNS / IPv6: from inside Docker on older Linux kernels, force IPv4 by passing --dns-opt="use-vc" or by adding A (not AAAA) resolution for the host.
Where do I report a bug or request a model?

Open an issue on our public repo. Include: request ID (from the response header X-Request-Id if present), the model + provider you targeted, the route strategy, and a redacted cURL that reproduces.

For a non-blocking model addition request, file it as a GitHub issue with the model-request label. For shipped updates and what’s next, watch /changelog.

Still stuck?

Get an API key and ship something today, or check the changelog for what’s new.

Get API Key