Rate Limits and API Errors
Telemetry endpoints use standard HTTP status codes. Clients should distinguish a request defect from a temporary service or capacity condition before retrying.
Plan-specific quotas and current limits may change. Treat the limits shown in the product and billing settings as the source of truth for an account; do not hard-code an undocumented global request rate.
Response classes
| Status | Meaning | Client action |
|---|---|---|
200 or 202 |
The operation succeeded or an asynchronous job was accepted | Read the response body and continue |
400 |
Invalid JSON, SQL, table name, field type, or request shape | Fix the request; do not retry unchanged |
401 |
Missing, invalid, or revoked API key | Replace the credential |
403 |
The key does not have the required scope | Use the correct scoped key |
404 |
The requested table, job, dashboard, or route does not exist | Verify the identifier and team |
409 or 422 |
The request conflicts with current state or cannot be applied | Inspect the error and change the operation |
429 |
The current request rate or quota was exceeded | Respect Retry-After when present and back off |
5xx |
Telemetry could not complete a valid request | Retry a bounded number of times with backoff |
Error bodies may include more specific context. Log the status, endpoint name, request ID, and a safe error category. Do not log the API key or the original event payload merely because a request failed.
Retry safely
Use exponential backoff with jitter for 429, 502, 503, and 504 responses. Cap both attempts and total elapsed time so a telemetry outage cannot exhaust an application worker.
delay = min(max_delay, base_delay * 2^attempt) + random_jitter
Do not retry a 400 response without modifying the request. Repeatedly sending an invalid schema or SQL query creates load without creating a path to success.
Preserve event identity
When retrying ingestion, reuse a stable event_id for the logical event. This makes duplicate delivery measurable and allows an idempotent consumer to recognize retries. A new identifier on every network attempt turns one outcome into several indistinguishable business events.
Use the duplicate event ID recipe to audit retry behavior.
Bound failure impact
Decide whether telemetry is on the critical path. For most product instrumentation, a temporary ingestion failure should be reported through a safe diagnostic channel without changing a customer response that already succeeded. For compliance or billing workflows, a durable queue may be appropriate.
For large result sets, use the asynchronous Query API rather than repeatedly retrying an interactive request. See API keys and authentication for scope rules.