"Failed to get token" errors

When a visitor clicks the orb and sees “Failed to get token” or the orb flashes red, the POST /v1/:siteId/token call failed. Open DevTools → Network → click the orb → watch the /token request.

Look at the status code

Status	Meaning
400 invalid_site_id	data-site-id is malformed — must be 8–32 alphanumerics
403 origin_not_allowed	The site’s URL doesn’t match a registered domain — see CORS errors
404 site_not_found	data-site-id is right format but doesn’t exist in your workspace
422 openai_key_missing	You’re on BYOK but haven’t configured an OpenAI key
429 rate_limited	Too many token requests from this IP or site
500 openai_error	OpenAI rejected our request (bad key, rate limit, outage)
503	Spelo API temporarily down — retry

400 invalid_site_id

The site_id must match [a-z0-9]{8,32}. Check:

• Is there leading/trailing whitespace in your data-site-id attribute?
• Did you accidentally paste the internal id (UUID) instead of the public site_id?

The public site_id is 8–12 alphanumerics and shown at the top of the Dashboard → Site detail page.

403 origin_not_allowed

The URL in your browser’s address bar doesn’t match any domain registered for this site. See CORS errors for the full walkthrough.

404 site_not_found

Possible causes:

• Your data-site-id was deleted from the dashboard
• You’re using a site_id from a different workspace
• Typo in the data-site-id attribute

Fix: go to Dashboard → Sites → copy the exact site_id from the row.

422 openai_key_missing

You’re on BYOK but haven’t entered an OpenAI key. Dashboard → Billing → OpenAI key → paste → save. Then retry.

Alternatively, switch back to managed: Dashboard → Billing → Use Spelo managed inference.

429 rate_limited

The response includes a Retry-After: N header (seconds). Wait and retry. If you’re legitimately hitting rate limits with normal traffic, contact support to request a higher limit on your site.

Burst thresholds:

• 60 token requests per minute per IP
• 200 token requests per minute per site
• 20 token requests per second per site (burst)

500 openai_error

Our API got a failure from OpenAI. The response body has more detail:

{
  "success": false,
  "error": {
    "code": "openai_error",
    "message": "invalid_api_key: Incorrect API key provided",
    "details": { "openai_status": 401 }
  }
}

Common OpenAI errors:

OpenAI message	Fix
invalid_api_key	Your OpenAI key is wrong or revoked — rotate
insufficient_quota	Your OpenAI account is out of credit — top up
rate_limit_exceeded	You hit OpenAI’s per-minute request limit — upgrade your OpenAI tier
model_not_found	OpenAI temporarily restricted the Realtime model — wait or contact OpenAI

503 Service Unavailable

Spelo API is temporarily overloaded or deploying. Retry with exponential backoff (1s, 2s, 4s, 8s, 30s). Check status.spelo.ai for an incident.

Local dev specifics

Working on localhost? The widget needs HTTPS or localhost. http://192.168.x.x won’t work — set up a self-signed cert or use ngrok / localtunnel / Caddy for HTTPS-wrapping localhost.

Tokens that succeed but WebRTC fails

If /token returns 200 but the orb then shows an error, the issue is the WebRTC handshake with OpenAI, not the token itself. Usually:

• Corporate firewall blocking UDP/STUN — tell the user to try a home network
• VPN interfering with ICE candidates — tell the user to disable VPN
• Browser denying microphone access — see Mic permission

Helpful headers

Every API response includes X-Spelo-Request-ID. Copy it when filing a support ticket — we can look up the exact request in our logs.

Still stuck?

Email support@spelo.ai with:

• Your site_id
• The failing request’s status code and response body
• The X-Spelo-Request-ID header
• A screenshot of the Network tab