Troubleshooting

Common errors and how to fix them

Troubleshooting

Quick reference for the most common errors you’ll hit when integrating with PolarGrid.

HTTP Error Reference

Code	Error	Cause	Fix
401	Invalid token: Not enough segments	Malformed token sent to a non-edge endpoint expecting a JWT	Edge endpoints accept pg_* keys directly. For auth-service endpoints, exchange your key via POST https://auth.polargrid.ai/v1/auth/session. See Authentication.
401	Token has expired	Your session JWT has expired (default TTL: 1 hour)	Request a new session token, or use direct API key auth (no JWT needed on edge endpoints).
403	{"Message": null}	Request blocked at the AWS infrastructure level (CloudFront/WAF)	Verify your API key is active in the dashboard. This error comes from AWS infrastructure, not the PolarGrid application.
402	Billing access denied	Your organization has no payment method or credits	Add a payment method in Settings > Billing, or contact support for credits.
404	Model not loaded	The model you requested is not deployed on this edge node	Call GET /v1/models to see available models, or switch to a different region.
405	Method Not Allowed	You sent an unsupported HTTP method (e.g., POST/PUT to a GET-only endpoint)	Check the API Reference for the correct HTTP method for each endpoint.
429	Rate limit exceeded	Too many requests in a short window	Back off and retry. Check Retry-After header for the wait time.
502	TTS backend error	The TTS synthesis engine failed (often bad voice ID or empty input)	Check that your voice parameter matches a valid voice ID and input is not empty.

Authentication Issues

”I’m sending my API key but getting 401”

Edge endpoints accept pg_* API keys directly — no token exchange needed:

curl https://api.yto-01.edge.polargrid.ai/v1/models \
  -H "Authorization: Bearer pg_your_key_here"

The SDK also sends pg_* keys directly. If you’re still getting 401:

• Check the key is active in Settings > API Keys (not revoked)
• Check the endpoint — some non-edge endpoints (e.g., management APIs) may require a session JWT
• Check the format — the key must start with pg_

For endpoints that require a session JWT, exchange your API key first:

TOKEN=$(curl -s -X POST https://auth.polargrid.ai/v1/auth/session \
  -H "Authorization: Bearer pg_your_key_here" \
  -H "Content-Type: application/json" \
  | jq -r '.session_token')

curl https://api.yto-01.edge.polargrid.ai/v1/models \
  -H "Authorization: Bearer $TOKEN"

“My key works in the playground but not in my code”

The playground uses the same auth flow as the SDK. Common causes:

• Wrong base URL: Use regional edge URLs like api.yto-01.edge.polargrid.ai, not api.polargrid.ai
• Missing Content-Type: POST requests need Content-Type: application/json
• Key permissions: Check that your key has read-write permissions in the dashboard

Region and Routing Issues

”Which region should I use?”

Use the autorouter for automatic region selection:

curl https://autorouter.polargrid.ai/v1/route

Or pick a specific region:

Region	Endpoint
Toronto	api.yto-01.edge.polargrid.ai
Vancouver	api.yvr-02.edge.polargrid.ai
Montreal	api.yul-01.edge.polargrid.ai

”I’m getting high latency”

1. Check you’re hitting the nearest region (use the autorouter)
2. First requests may be slower due to model cold start
3. Use GET /health to check if the edge node is healthy before sending inference requests

Browser / Frontend Issues

”ReferenceError: process is not defined”

The SDK references process.env for configuration fallbacks. In browser environments (Vite, esbuild, Parcel), process is not defined.

Fix: Pass all configuration explicitly at init:

const client = new PolarGrid({
  apiKey: 'pg_your_key',
  baseUrl: 'https://api.yto-01.edge.polargrid.ai',
});

“CORS error when calling the API from my frontend”

Edge inference endpoints include Access-Control-Allow-Origin: * via CORS middleware, so browser-origin requests work directly. If you’re seeing CORS errors:

1. Check the URL: Make sure you’re hitting a regional edge URL (api.yto-01.edge.polargrid.ai), not a misconfigured proxy
2. Check the auth endpoint: If the CORS error is on auth.polargrid.ai, ensure your auth-service deployment includes CORS headers (added in POL-230)
3. Check preflight: OPTIONS requests must return 2xx with CORS headers — if your proxy strips them, the browser blocks the real request

TTS Issues

”TTS returns 0 bytes or empty audio”

Common causes:

• Empty input field
• Invalid voice parameter (check available voices in the TTS docs)
• Quoted text with special characters can sometimes cause issues

”TTS generation time is very slow”

TTS generation time scales linearly with input length for batch requests. For long text, consider:

• Breaking text into shorter segments
• Using streaming TTS (stream: true) for faster time-to-first-audio

Still Stuck?

• Check the API Reference for endpoint details
• Review the Error Handling guide for SDK error types
• Contact support at [e-mail]