Troubleshooting

Work through the matching section before opening a ticket. If you're still stuck, see When to contact support.

In the app

"Start Pro to launch": I can't launch my agent or sequence during the trial

What it means: the 14-day Pro trial lets you build agents, plays, sequences and LinkedIn steps, but launching them needs a paid plan. That includes turning an agent on, Run now, Run a test, Test on 5 records and launching a sequence. You'll see:

• Agents: a dialog Start Pro to launch with "Start an eligible paid plan to launch agents. Your saved draft will remain available."
• Sequences: the Launch button tooltip "Choose a paid plan to launch this sequence", and the dialog Start Starter to launch.

Fix: go to Settings → Plans & billing. During the trial the plan cards read Start Pro now and Start Starter now. Confirming the "Start Pro today?" (or "Start Starter today?") dialog ends the trial and starts the plan on the card you added; the plan's credits are added on top of the trial credits you have left. Your drafts stay as they are.

• Agents need Pro (or Enterprise). Starter doesn't include Agents or LinkedIn steps.
• Email sequences and call tasks work on Starter or Pro.

On Pro you can have 5 active agents at a time. A 6th shows "Your plan allows 5 active agents. Pause one to activate another." Enterprise has no limit. See Pro free trial.

"Credit top-ups aren't available during your trial"

What it means: buying one-time credits is turned off while the Pro trial runs ("Credit top-ups aren't available during your trial. Pick a plan to keep enriching.").

Fix: start a paid plan from Settings → Plans & billing (Start Pro now or Start Starter now), then use Buy more credits if you still need more. Starting the plan also adds its monthly credits.

"You're out of free searches": Find People won't search

What it means: you've used your workspace's search allowance. Searches cost no credits, but each plan includes a set number, shared by the People and Companies tabs:

On Free you'll see You're out of free searches with "You've used your 5 available searches. View plans to keep searching." and Upgrade your plan. On Starter and during the trial the message is "You've used this period's searches. Choose a paid plan to keep searching." The quota strip above the search button counts down as you go ("No free searches left", "No included searches left").

Fix: move to Pro for unlimited searches (from Free, Starter adds 250 a month). During the trial, Start Pro now in Settings → Plans & billing. Buying credits doesn't add searches.

"Hourly preview limit reached. Try again later."

What it means: you paged deep into one set of search results. The first block of results is never limited; loading further blocks of the same results is limited per hour for each workspace.

Fix: wait and try again, or narrow your filters. Add to list isn't affected by this limit, so you can add the people you found straight away.

A sequence lead says "Waiting", "Paused" or "Stopped"

What it means: a lead's run is held or ended, and the label tells you why. An email that can't go out yet holds the lead; it's never skipped.

Full list and fixes: Build a sequence: troubleshooting.

Sequences is locked in the sidebar

What it means: your plan doesn't include Sequences, so the tile shows a lock and the tooltip "Choose a plan with Sequences". Inbox and Tasks are hidden for the same reason.

Fix: Sequences are on Starter (email and call tasks), Pro and Enterprise (plus LinkedIn steps). Choose a plan in Settings → Plans & billing. See Sequences.

Clu stopped in the middle of a task

What it means: each Clu request has limits. When it reaches one, Clu writes "Done so far:" with what it finished and offers a Continue reply. The message tells you which limit:

Actions Clu runs for you (enrich, validate, skills) always show their cost on a confirmation card first. On the Free plan Clu isn't charged. See What Clu costs.

Clu isn't answering in Slack

Check, in order:

1. Plan: Clu in Slack is on Pro and Enterprise (and the Pro trial). On Free and Starter, Clu doesn't reply at all.
2. Connected: an admin connects it in Integrations → Clu by Cleanlist AI → Connect Slack.
3. Linked: the first time you message Clu, it asks you privately to connect your Cleanlist account. Finish that step, then ask again.
4. Where you asked: DM Clu or @mention it. Clu doesn't work in group DMs or channels shared with other companies, and a private channel needs Clu invited first.
5. Thread owner: Clu answers only the person who started the thread ("This thread belongs to someone else…"). Start your own message.

Setup and limits: Clu in Slack.

"Open Cleanlist on Desktop"

What it means: the app needs a screen at least 1,024 pixels wide. On phones, tablets and narrow windows you'll see "Cleanlist is a desktop-only platform built for managing leads, enrichment, and outreach."

Fix: open app.cleanlist.ai (opens in a new tab) on a computer. If you're already on a computer, widen or maximize the browser window, or zoom out.

Imported rows show an amber triangle or "Pending..."

What it means: after a CSV import, Cleanlist looks up each row's profile. Rows it couldn't fill keep an amber triangle on the name with "Profile not filled in" and a reason, such as "No LinkedIn profile matched this name and company.", "Several people match this name and company.", "Not enough to look this person up: add a first and last name with a company, or a LinkedIn URL." or "Not looked up: your workspace ran out of credits." Cells that read "Pending..." are still being enriched.

Fix: add the missing LinkedIn URL or name and company, top up if you ran out of credits, and run the enrichment again. If "Pending..." doesn't change, refresh the page. See Import a CSV.

My agent's play turned itself off

What it means: a play is paused after its trigger fails 3 checks in a row with the same problem you can fix, such as a disconnected CRM or app, not enough credits, or too many records. The owner gets an alert, and the play shows "Paused" with the reason.

Fix: fix the cause shown, then turn the play or agent back on. See Agents.

My CRM push isn't working

Checklist:

1. Open Integrations in the sidebar. A connected CRM shows Linked; an amber Reconnect badge means you need to sign in again.
2. Open the CRM's settings (gear icon on its card) and check the Field Mapping tab for the object you're writing to.
3. Check the Logs tab: it lists every call Cleanlist made to your CRM, and failed rows can be retried.
4. Check the Usage tab: when the daily call cap is reached, "Syncs pause until usage resets or you raise the cap below."
5. For Export to CRM columns in a list, open the column to see each row's status (Pending, Running, Success, Failed, Skipped) and use Retry.

CRM sync and Export to CRM need Pro or Enterprise. See HubSpot and Salesforce.

My CRM connection stopped working

What it means: usually an expired sign-in, 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:

• HubSpot or Salesforce: in Integrations, click the amber Reconnect badge on the card. Any member can do this. The Reconnect button inside the CRM's settings is for admins and the person who connected it.
• Lemlist: Lemlist connects with an API key. Reconnect with a fresh key from Lemlist Settings → Integrations.

My push or enrichment looks stuck

What it means: bulk runs take time; that alone isn't a sign something is broken.

Guidance: bulk operations can take up to about 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 with the list and what you ran.

Public API

"I'm getting a 401 Unauthorized"

What it means: Cleanlist couldn't authenticate the request ("Invalid or expired API key").

Checklist:

1. 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
2. Confirm the key starts with clapi_
3. Run a sanity check:

   curl https://api.cleanlist.ai/api/v1/public/auth/validate-key \
     -H "Authorization: Bearer $CLEANLIST_API_KEY"
4. If valid: false or 401: open Settings → API keys and check that the key shows Active and hasn't passed its expiry
5. If it was revoked or expired, create a new one with Create API key

"I can't create an API key"

What it means: API keys need Pro or Enterprise. On Free and Starter the API keys page shows "The Cleanlist API." with an upgrade button, and the API answers "This feature requires the Pro plan or higher." During the Pro trial the answer is "Public API access is not included during the trial."

Fix: move to Pro in Settings → Plans & billing. If you only want Cleanlist inside Claude, the MCP connector works on Starter, Pro, Enterprise and the Pro trial without an API key.

"I'm getting a 402 Payment Required" or insufficient_credits

What it means: your workspace doesn't have enough credits for the request. The legacy v1 API answers 402 Payment Required; API v2 answers 400 with the code insufficient_credits (see Errors and rate limits).

Fix: buy credits in Settings → Plans & billing → Buy more credits, or click Add next to your balance at the bottom of the sidebar. Check the balance from the API:

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

Misses cost 0 credits. To avoid paying twice, resend only the contacts that didn't succeed.

"I'm getting a 422 Validation Error"

What it means: the request body didn't match the endpoint's schema. Usually a missing field combination.

Fix: for POST /api/v1/public/enrich/bulk, each contact must include either:

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

The response names the problem and where it is:

{
  "error": {
    "code": "validation_error",
    "problem": "Request body failed validation.",
    "details": {
      "errors": [
        {
          "loc": ["body", "contacts", 7],
          "msg": "Each contact must include linkedin_url OR ..."
        }
      ]
    }
  }
}

In this example, fix contacts[7].

"Bulk enrichment supports up to 250 contacts per request"

What it means: you sent more than 250 contacts to /enrich/bulk.

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'm getting 429 Too Many Requests"

What it means: you hit a rate limit:

• 60 requests per minute per organization, all keys and members combined, on every public endpoint.
• 30 requests per minute per API key on the v2 endpoints.
• People search (POST /people/find) with an API key: 60 searches per UTC day per organization.

The response includes a Retry-After header in seconds.

Fix: wait for Retry-After, or back off with exponential backoff and jitter:

import time, random, requests
 
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 hit 429s during normal use, contact us.

"I submitted a workflow but never got the webhook"

What it means: webhook delivery may have failed. Webhooks are a v1 feature (the webhook_url on /enrich/bulk).

Checklist:

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

   curl "https://api.cleanlist.ai/api/v1/public/webhooks/deliveries?workflow_id=$WORKFLOW_ID" \
     -H "Authorization: Bearer $CLEANLIST_API_KEY"
3. Look at the attempt_number, status, response_status_code, and error_message fields
4. Common reasons for failure:
   • Endpoint returned 5xx (a bug on your server)
   • Endpoint returned 4xx (your auth or routing rule rejected the payload)
   • Connection timed out (your endpoint took longer than 10 seconds)
   • DNS or TLS error (URL or certificate issue)
5. 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=.... See Receiving Webhooks.

"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 for data sources to have 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 a different identifier (name + company instead of a LinkedIn URL, or the other way round)
• Remember that the waterfall only keeps work emails that are verified or likely valid, so a contact whose only known address is risky or invalid comes back empty (waterfall enrichment)

You're not charged for empty results.

"I created an API key but lost it"

What it means: Cleanlist shows a key only once, under "New API key", when you create it.

Fix: in Settings → API keys → Your API keys, click Revoke on the lost key, then create a new one with Create API key. Store it in a secret manager this time.

"I hit the maximum number of API keys"

What it means: you already have 10 active keys in this workspace.

Fix: revoke an unused key in Settings → API keys, or use Revoke all to start fresh.

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

What it means: legacy v1 /enrich/bulk results are saved to a protected list named Extension Leads.

Fix: open Lead Lists and look for Extension Leads. See Lead Lists (v1).

When to contact support

If you've worked through this page and you're still stuck, use Help and support at the bottom of the sidebar for live chat, or email support with:

• The feature or endpoint you're using
• The exact error message (and status code, for the API)
• The list, agent, sequence, workflow_id or key name involved
• For the API, a sample request body with secrets removed

We respond within one business day.

Related

• Finding your way around Cleanlist
• Settings
• Pro free trial
• Build a sequence
• Clu in Slack
• API errors (v2)
• API authentication (v2)
• Receiving Webhooks