Browse developer documentation
Get started
Errors, limits and retries
Handle report failures, rate limits and route-specific ingestion responses.
Check HTTP status before reading data
Reports, website setup, server events and changelog use a status/data success envelope. Their failures use status: error with a numeric code and a human-readable message. Payment, crawler and tracker routes use the raw shapes documented on their endpoint pages.
Never replace a failed report with zeros or public sample data.
| Status | Meaning | Action |
|---|---|---|
| 400 | Invalid input or cursor | Correct the parameters; restart expired pagination |
| 401 | Missing, invalid or expired credential | Use the current key or reconnect/refresh OAuth |
| 403 | Missing scope, role or website allowance | Review permission or current plan |
| 404 | Unknown or inaccessible site/report | List websites again; check the route |
| 413 | Crawler batch too large | Send no more than 500 hits |
| 429 | Rate limit reached | Wait until X-RateLimit-Reset |
| 500 | Unexpected server failure | Retry reads with bounded backoff |
| 503 | Complete report unavailable | Retry or shorten the date range |
{
"status": "error",
"error": {
"code": 400,
"message": "Choose a row limit between 1 and 500."
}
}Report API rate limit
Endpoints using the shared API authenticator enforce 120 requests per minute per credential per server instance. Read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). This is not a global account-wide quota guarantee.
On 429, wait until the reset time, then retry with a small random delay. For transient read failures, use a bounded exponential backoff. Stop retrying unchanged 400/401/403 requests.
Crawler and normalized payment routes have different ingestion controls and do not use these report rate-limit headers. Crawler monthly caps are documented on the crawler endpoint page.
Retry writes carefully
Normalized payments deduplicate by website, provider and external transaction ID. Reuse the same stable ID when retrying the same payment. A separate refund needs its own stable ID.
Goal calls and crawl batches do not accept a general idempotency key. Blind retries after an uncertain result can duplicate counts. Website creation reuses an existing domain within the workspace; still require the account holder's confirmed details.