Who this is for: self-serve plans (Free, Starter, Pro, Scale). If you bought a Cleanlist AppSumo lifetime deal, your features, limits, and pricing are different — see the AppSumo documentation instead. Support agent: confirm whether the user is self-serve or AppSumo before giving plan-specific advice.

TL;DR: Check the API key, check the credit balance, check the request shape, then check GET /public/webhooks/deliveries if you're using webhooks. Most issues fall into one of those four buckets.

Troubleshooting

If something isn't working, run through this list before opening a support ticket. Most issues are one of these.

"I'm getting a 401 Unauthorized"

What it means: Cleanlist couldn't authenticate the request.

Checklist:

Confirm the header is exactly Authorization: Bearer clapi_...

Not X-API-Key
Not basic auth
The word Bearer is required, with a space before the key

Confirm the key starts with clapi_
Run a sanity check:

   curl https://api.cleanlist.ai/api/v1/public/auth/validate-key \
     -H "Authorization: Bearer $CLEANLIST_API_KEY"

If valid: false or 401: open the portal → Settings → API Keys and confirm the key is still active
If the key was rotated, generate a fresh one

"I'm getting a 402 Payment Required"

What it means: Your organization is out of credits.

Fix: Top up in the portal under Settings → Billing. New credits land within seconds of the Stripe payment.

curl https://api.cleanlist.ai/api/v1/public/credits/balance \
  -H "Authorization: Bearer $CLEANLIST_API_KEY"

Failed enrichments cost 0 credits, so retrying after a top-up is safe — you won't be double-charged for the rows that already succeeded.

"I'm getting a 422 Validation Error"

What it means: One or more contacts didn't pass Pydantic validation. Usually a missing field combo.

Fix: Each contact must include either:

linkedin_url, or
first_name + last_name + (company_domain or company_name)

The detail array tells you which contact index is bad:

{
  "detail": [
    {
      "loc": ["body", "contacts", 7],
      "msg": "Each contact must include linkedin_url OR ..."
    }
  ]
}

In this example, fix contacts[7].

"My bulk request is failing with 'Bulk enrichment supports up to 250 contacts per request'"

What it means: You sent more than 250 contacts.

Fix: Split the input client-side:

def chunked(iterable, size):
    for i in range(0, len(iterable), size):
        yield iterable[i:i + size]for batch in chunked(all_contacts, 250):
    submit_batch(batch)

You can submit batches in parallel, but watch the rate limit.

"I submitted a workflow but never got the webhook"

What it means: Webhook delivery may have failed.

Checklist:

Confirm your webhook_url is HTTPS, publicly reachable, and ACKs with 2xx within 10 seconds
Query the delivery log:

   curl "https://api.cleanlist.ai/api/v1/public/webhooks/deliveries?workflow_id=$WORKFLOW_ID" \
     -H "Authorization: Bearer $CLEANLIST_API_KEY"

Look at the attempt_number, status, response_status_code, and error_message fields
Common reasons for failure:

Endpoint returned 5xx (your server bug)
Endpoint returned 4xx (your auth or routing rule rejected the payload)
Connection timed out (your endpoint took longer than 10s)
DNS / TLS error (URL or cert issue)

Fix the endpoint and re-submit the workflow

If all 5 attempts failed, the result is still available via GET /api/v1/public/enrich/status?workflow_id=....

"My enrichment came back empty"

What it means: The waterfall ran but no provider found verified data.

Why it happens:

The contact is at a stealth-mode company
The contact is too new (LinkedIn / databases haven't indexed them yet)
The company domain doesn't match the contact's actual employer
The linkedin_url is malformed or points to a deactivated profile

Fix:

Try sending with a different identifier (name + company instead of LinkedIn URL, or vice versa)
If you're using partial, try full to engage phone providers as a backup signal
Check email_status — risky results often have a working email even if it's not marked verified

You're not charged for empty results, so retrying is free.

"I'm getting 429 Too Many Requests"

What it means: You hit a rate limit — 60 requests/minute per organization (all keys and members combined) or 30 requests/minute per API key, applied across the whole API (not per endpoint).

Fix: Back off with exponential backoff + jitter:

def call_with_backoff(method, url, **kwargs):
    for attempt in range(6):
        r = requests.request(method, url, **kwargs)
        if r.status_code != 429:
            return r
        time.sleep(2 ** attempt + random.random())
    r.raise_for_status()

If you're hitting 429s during normal use, [contact us](mailto:[email protected]) — your plan may need a higher rate limit.

"I created an API key but I lost the secret"

What it means: Cleanlist only shows the secret once at creation, by design.

Fix: Revoke the key and generate a new one. Use a secret manager next time so you don't lose it.

# Revoke
curl -X POST "https://api.cleanlist.ai/api/v1/api-keys/$KEY_ID/revoke" \
  -H "Authorization: Bearer $CLERK_SESSION_JWT"

Or use the portal: Settings → API Keys → Revoke.

"I hit the 'maximum API keys' limit"

What it means: You already have 10 active keys and tried to create an 11th.

Fix: Revoke an unused key first (POST /api/v1/api-keys/{key_id}/revoke) or use revoke-all if you want to start fresh.

A column is stuck on 'pending'

What it means: The processing queue has your job but hasn't reached your row yet.

Checklist:

Open the column header menu — does it show progress (e.g., "120 / 500 done")?
If progress is moving, just wait
If progress is 0 and it's been more than a few minutes, refresh the page (the live update may be stuck)
If still stuck after a refresh, [contact support](mailto:[email protected]) with the column id

"My Public API enrichments don't show up in any lead list"

What it means: They are in your Extension Leads list — you may not have noticed it.

Fix: Open the portal → Lead Lists → look for a list named Extension Leads. Every Public API enrichment lands there. See Lead Lists for the full explanation.

"My CRM push isn't working"

Checklist:

Open Settings → Integrations and confirm the connection is healthy
Check the field mapping for the destination object
Look at the Action Column's per-row error messages — they include the destination's response
Most CRM failures are auth-token expiration or required-field validation; both are visible in the error message

"My CRM connection stopped working"

What it means: Usually an expired OAuth token, or a stale browser session.

Quick fixes: refresh the page, check your internet connection, clear your browser cache, and try Chrome, Firefox, or Edge.

Reconnect: if HubSpot, Salesforce, or Lemlist stops working, go to Integrations and reconnect — this refreshes expired OAuth tokens. For org-level connections like Salesforce, the original user who connected it may need to reconnect.

"My push or enrichment looks stuck"

What it means: Bulk runs take time — not a sign something is broken.

Guidance: Bulk operations can take up to ~4 hours. Refresh the page to confirm progress before assuming something is wrong, and don't assume it's broken after only ~15 minutes. If it truly hasn't progressed for a long while, [contact support](mailto:[email protected]) with your workflow and session details.

When to reach out to support

If you've worked through this list and you're still stuck, [email support](mailto:[email protected]) with:

The endpoint or feature you're using
The exact error message and status code
The workflow_id (or key_id, or column_id) involved
A sample request body (with secrets redacted)

We respond within one business day.

Full documentation: docs.cleanlist.ai/guides/troubleshooting

Troubleshooting common errors

Troubleshooting

"I'm getting a 401 Unauthorized"

"I'm getting a 402 Payment Required"

"I'm getting a 422 Validation Error"

"My bulk request is failing with 'Bulk enrichment supports up to 250 contacts per request'"

"I submitted a workflow but never got the webhook"

"My enrichment came back empty"

"I'm getting 429 Too Many Requests"

"I created an API key but I lost the secret"

"I hit the 'maximum API keys' limit"

A column is stuck on 'pending'

"My Public API enrichments don't show up in any lead list"

"My CRM push isn't working"

"My CRM connection stopped working"

"My push or enrichment looks stuck"

When to reach out to support

Related