> ## Documentation Index > Fetch the complete documentation index at: https://polargrid.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](/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](https://app.polargrid.ai/dashboard/settings). 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](/api-reference/overview) 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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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: ```javascript theme={null} 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](/api-reference/text-to-speech)) * 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](/api-reference/overview) for endpoint details * Review the [Error Handling](/guides/error-handling) guide for SDK error types * Contact support at [support@polargrid.ai](mailto:support@polargrid.ai)