Errors & Rate Limits

Error shapes

API v2 returns errors in one of three shapes. All three put the details under a top-level error object.

1. The public error envelope

Errors raised by an endpoint (validation, quotes, credits, scopes, not found, conflicts, provider failures):

{
  "error": {
    "code": "insufficient_credits",
    "problem": "This enrich_list call requires 110 credits; organization has 40.",
    "fix": "Top up at app.cleanlist.ai/billing, or reduce the scope of the call.",
    "retryable": false,
    "docs_url": "https://docs.cleanlist.ai/errors/insufficient-credits",
    "request_id": "req_4f1c2a9b3d6e7f80",
    "estimated_cost_credits": 110,
    "available_credits": 40,
    "shortfall_credits": 70
  }
}

Fields with no value are left out of the body.

2. Request body validation (422)

When the JSON body doesn't match the endpoint's schema (wrong types, unknown fields, missing required fields, or both halves of a one-of body), the request is rejected before the handler runs with HTTP 422 in the public envelope, code validation_error (lowercase), problem: "Request body failed validation." and the per-field errors in details.errors:

{
  "error": {
    "code": "validation_error",
    "problem": "Request body failed validation.",
    "fix": "Check the request matches the endpoint schema. For a one-of body (e.g. add_leads_to_list: lead_ids XOR task_id), send exactly one variant's fields and nothing from the other.",
    "retryable": false,
    "docs_url": "https://docs.cleanlist.ai/errors/validation-error",
    "request_id": "req_...",
    "details": { "errors": [ { "type": "extra_forbidden", "loc": ["body", "domain"], "msg": "Extra inputs are not permitted" } ] }
  }
}

Checks that run inside the handler (an unknown filter key, an unknown tool in /credits/estimate) return the same validation_error code with HTTP 400. This shape is also used by the legacy v1 endpoints.

3. The generic shape (401, 403 plan blocks, 429)

Authentication failures, plan and trial blocks, and rate limits are raised before the endpoint runs and use a shorter shape with an uppercase code and a message (no problem, docs_url or request_id):

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Public API is limited to 60 requests per minute per organization.",
    "trace_id": "..."
  }
}

Plan blocks put the reason in details, for example {"error": "feature_gated", "feature": "api_access", "current_tier": "starter", "required_tier": "pro"}. Robust clients read error.code from either shape and compare it case-insensitively.

Error code reference

Codes in the public envelope, grouped by what went wrong. The anchor for each code is the code with dashes, so docs_url links land on the right row.

Request and validation

Quotes and credits

Access, plan and limits

Not found

Conflicts

Providers, sync and server

Codes from routes the Cleanlist MCP uses

These come from v2 routes built for the Cleanlist MCP (folders, skills, CRM reads, filter values). You'll mostly see them in Claude.

Generic codes (uppercase)

Older versions of these docs listed invalid_token, workflow_timeout, version_deprecated, invalid_filter_id, estimate_token_mismatch and field_mapping_required. The API doesn't return any of them.

Rate limits

These limits apply to every API v2 request at the same time:

Signed-in app sessions are held to the per-organization limit but not the per-key limit.

People Finder has its own limits

POST /people/find is metered on top of the limits above:

The daily cap is the one most integrations hit first. A backfill that runs one search per record runs out after 60 records and gets 429 until midnight UTC, with the message "People Search rate limit exceeded. Public API keys are limited to 60 searches per day per organization. Use the Cleanlist MCP for higher throughput." Each cursor page counts as a search. Pull bigger pages (up to 100 rows each) rather than many narrow searches, or use the Cleanlist MCP for higher volume. Company search and find-at-companies don't count toward this cap.

Handling 429

A rate-limited request returns HTTP 429 in the generic shape:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Per-API-key rate limit exceeded. Each API key is limited to 30 requests per minute. Spread traffic across keys or wait."
  }
}

A standard Retry-After header (in seconds) comes with every 429, so generic HTTP clients can back off without parsing the body. Honor it, then retry:

import time, requests
 
def call_with_backoff(method, url, **kw):
    while True:
        r = requests.request(method, url, **kw)
        if r.status_code != 429:
            return r
        wait = int(r.headers.get("Retry-After", "2"))
        time.sleep(wait)

async function callWithBackoff(url, opts) {
  while (true) {
    const r = await fetch(url, opts);
    if (r.status !== 429) return r;
    const wait = parseInt(r.headers.get("Retry-After") || "2", 10);
    await new Promise((res) => setTimeout(res, wait * 1000));
  }
}

For the daily People Finder cap, Retry-After can be many hours; stop and resume after midnight UTC instead of sleeping in a loop.

Learn more

• Authentication & scopes
• Credits & the quote model
• People Finder API
• Enrichment endpoints
• API v2 overview