Handle API rate limits, errors and request logs

Budget requests at account level

Every API key and project on one account shares 250 requests per rolling minute and a 30-per-second burst limit. Applicable concurrency bounds also limit simultaneous work. There are no usage credits and no extra allowance created by rotating a key or opening another project. Count notebook requests, application clients, reference simulator calls and MCP activity together when planning traffic. A rolling minute is not necessarily reset at the top of a wall-clock minute, so a burst near a minute boundary can still affect the following request window.

Read response rate and retry information

Inspect X-RateLimit headers on authenticated responses and honor Retry-After or retry_after_ms when supplied. A retry instruction gives your client a concrete waiting boundary; immediately resending in several parallel loops can make the problem persist. Use bounded backoff for appropriate transient responses and keep a maximum retry budget. Reuse a result when your question has not changed, and narrow heavy queries instead of requesting a huge range repeatedly. Rate capacity, concurrent work and upstream availability are different constraints even when more than one can lead to a temporary refusal.

Branch on structured errors

Use the error code in client logic rather than matching a human-readable sentence. A 400 normally means parameters or request shape need correction. A 401 concerns missing or refused authentication. A 403 can concern API subscription, dataset or allowed history. A 429 can reflect an account limit or cooldown, and a 503 can describe service, input or preparation availability. Read details and retry information before deciding whether to repeat the request. Repeating an invalid parameter unchanged is not a useful transient-error recovery strategy.

1. Record the HTTP status, error code, parameter details and request ID.
2. Correct permanent input or authentication problems before retrying.
3. For a retryable response, honor its wait instruction and use bounded backoff.

Use Request logs for the concrete request

Open Developers → Request logs and locate the relevant route and approximate time. Compare its status and request identifier with the response captured by your client. A request that never reached the API because the browser or network failed can need a different investigation from a logged endpoint refusal. Keep the running environment and account fixed while comparing, since logs for another account or a different deployment cannot explain this request. Use the narrowest useful time and route context rather than assuming a similarly named recent call was the same one.

Read Usage as activity evidence

Developers → Usage helps inspect recorded activity over the available time grouping. Usage is not a credit balance, and a chart's displayed total is not permission to exceed a rolling request or concurrency limit. Compare the relevant period with your client schedule and other active integrations. If bursts occur when a notebook, MCP client and dashboard all refresh together, spread work deliberately rather than creating more keys. A low historical total also does not rule out a short concentrated burst that reached the per-second boundary.

Diagnose authentication cooldown separately

Many failed authentication attempts from one network can produce a temporary cooldown. Check the complete key, header form, project activity and intended base URL before trying again. A revoked or lost key needs the correct replacement, not repeated guesses based on its public prefix. Keys in query strings are deliberately rejected. If authentication succeeds but access is denied, inspect the API plan and dataset instead of resetting the key blindly. A terminal subscription and an active browser session do not themselves authorize a public developer request.

Send a precise support report

Include X-Request-ID, the route, safe parameters, approximate time with time zone, status, structured code and retry information. State whether the problem appeared in REST, the simulator, MCP or a WebSocket handshake. Add relevant source coverage when a request succeeded but its data was partial or delayed. Do not include the full developer key, session cookie or raw private configuration. Provider acceptance and live source availability need actual evidence, so describe the response you observed instead of assuming a configured endpoint or a sample document proves the upstream was working.