Error Handling

The widget surfaces backend errors through the onError callback (and through the error argument of streaming callbacks if you’re using the headless SDK directly). Most errors are network failures or transient backend hiccups that just need a retry — but a few have specific shapes worth handling explicitly.

Throttling (429)

Rate limits come from the project’s active subscription plan and are enforced per minute across three independent axes — API key, source IP, and user session. Hitting any one axis returns 429.

Response headers

Successful requests on rate-limited endpoints carry the limit-aware headers (reflecting the API-key axis):

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55

429 Too Many Requests

When throttled, the response carries Retry-After (seconds) and a body shaped like:

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded (apiKey). Please try again later.",
  "retryAfter": 30
}

message includes the layer that triggered the throttle (apiKey, session, or ip) — useful for debugging which axis is hitting first.

Handling 429

• Implement exponential backoff before retrying — the SDK doesn’t do this automatically inside onError
• For chatty UIs (rapid typing, autosuggest), throttle client-side so user-driven bursts don’t burn your quota
• Use Test keys during development so production counters stay clean
• Watch usage in Analysis — if you’re trending toward your plan’s ceiling, plan an upgrade before hitting it