Errors

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits. Required: 33.0 for 3 prospects, Available: 12. Please purchase more credits to continue.",
    "trace_id": "f7a1b3c2..."
  }
}

{
  "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_a1b2c3d4e5f6a7b8",
    "details": {
      "errors": [
        {
          "type": "value_error",
          "loc": ["body", "contacts", 7],
          "msg": "Value error, Each contact must include linkedin_url OR first_name + last_name + (company_domain or company_name). To discover people at a company from a domain alone, call POST /api/v2/people/find first, then pass the resulting rows back to /enrich/bulk."
        }
      ]
    }
  }
}

{ "error": { "code": "AUTHENTICATION_INVALID", "message": "Invalid or expired API key" } }

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

import random
import time
import requests
 
def call_with_backoff(method, url, **kwargs):
    for attempt in range(6):  # 1 try + 5 retries
        r = requests.request(method, url, **kwargs)
        if r.status_code != 429:
            return r
        wait = int(r.headers.get("Retry-After", 2 ** attempt))
        time.sleep(wait + random.uniform(0, 0.5))
    r.raise_for_status()

def safe_enrich(payload, api_key):
    r = requests.post(
        "https://api.cleanlist.ai/api/v1/public/enrich/bulk",
        headers={"Authorization": f"Bearer {api_key}"},
        json=payload,
    )
    if r.status_code == 401:
        raise RuntimeError("Cleanlist API key is invalid, revoked or expired")
    if r.status_code == 402:
        raise RuntimeError(r.json()["error"]["message"])
    if r.status_code == 422:
        raise ValueError(r.json()["error"]["details"]["errors"])
    if r.status_code == 429:
        raise TransientError(r.headers.get("Retry-After"))
    r.raise_for_status()
    return r.json()