Developer API · updated 2026-08-22

Errors, rate limits and plan limits

The API uses a consistent error envelope, per-key rate limits, and a daily usage window on the free plan. This article documents every error code you can receive and exactly how the limits work, so your integration can handle each case gracefully.

1. 1

   The error envelope

   Every error is JSON with the same shape:

   { "error": { "code": "...", "message": "..." } }

   Some errors add fields next to it (for example upgrade_url on plan-limit errors). Always branch on error.code, never on the human message, which can change.

2. 2

   HTTP status codes

   200 success (and 200 with existing:true when a lead POST deduplicates), 201 lead created, 400 invalid_body or invalid_parameter, 401 unauthorized (missing, invalid or revoked key), 403 access_disabled (company gate turned off), 404 not_found, 405 method_not_allowed, 429 rate or plan limits, 500 internal (safe to retry with backoff).

3. 3

   Rate limit: 60 requests per minute per key

   All plans. Exceeding it returns 429 with code rate_limited and a Retry-After header in seconds. Spread bursts or add a small queue; the counter resets each minute.

4. 4

   Free plan: the 10-minute daily window

   On the free plan, your first API call of the day (company local time) opens a 10-minute window. Calls inside the window are served normally; after it closes, read calls return 429 with code daily_window_ended and an upgrade_url, until the next day. The X-DC-Window-Remaining response header tells you the seconds left. Design free-plan integrations as one scheduled sync burst per day.

5. 5

   Free plan: 200 leads per day

   POST /v1/leads does NOT consume the 10-minute window (a lead can arrive at any hour). Instead it has its own quota of 200 leads per day on the free plan; beyond it you get 429 lead_quota_exceeded. Paid plans have no window and no lead quota.

6. 6

   Paid plans: unlimited

   Companies on a paid plan have unlimited API access: no daily window, no lead quota. The technical 60 requests/minute per key limit still applies to protect the platform.