Diagnose and fix Clay common errors and exceptions. Use when encountering Clay errors, debugging failed requests, or troubleshooting integration issues. Trigger with phrases like "clay error", "fix clay", "clay not working", "debug clay".
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill clay-common-errorsLoading…
Quick reference for the top 12 most common Clay errors across webhooks, enrichment columns, HTTP API columns, Claygent, and CRM integrations. Each error includes the exact symptom, root cause, and fix.
Symptom: Data sent to webhook URL but rows never appear in table.
Cause: Invalid JSON payload or missing Content-Type header.
Fix:
# Always include Content-Type header
curl -X POST "$CLAY_WEBHOOK_URL" \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "domain": "example.com"}'
# Validate JSON before sending
echo '{"email": "[email protected]"}' | jq . || echo "Invalid JSON!"
Symptom: 404 Not Found when POSTing to webhook URL.
Cause: Table was deleted, webhook was replaced, or URL was copied incorrectly.
Fix: Open the Clay table, click + Add > Webhooks > Monitor webhook, and re-copy the URL. Each table has a unique webhook ID.
Symptom: Enrichment column returns empty for most rows.
Cause: Input data quality is poor (personal email domains, invalid domains, missing fields).
Fix:
// Pre-validate before sending to Clay
const personalDomains = ['gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com', 'icloud.com'];
function isEnrichable(row: { domain?: string; email?: string }): boolean {
if (!row.domain || !row.domain.includes('.')) return false;
if (personalDomains.some(d => row.domain!.endsWith(d))) return false;
if (row.email && personalDomains.some(d => row.email!.endsWith(d))) return false;
return true;
}
Symptom: Enrichment stops mid-table with credit error.
Cause: Monthly credit allowance exhausted.
Fix: Check credit balance in Settings > Plans & Billing. Options:
Symptom: Webhook stops accepting new submissions silently.
Cause: Each webhook source has a hard limit of 50,000 submissions.
Fix: Create a new webhook source on the same table. The 50K limit persists even after deleting rows -- you must create a fresh webhook.
Symptom: Red error indicator on HTTP API enrichment column cells.
Cause: Target API URL is wrong, auth header is incorrect, or response format unexpected.
Fix:
curl -X POST "https://api.example.com/endpoint" \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"test": "data"}'
Symptom: Claygent column returns empty or generic responses.
Cause: Prompt is too vague, company is too small/private, or website blocks bots.
Fix:
Symptom: Credits consumed on rows that were already enriched.
Cause: Table-level auto-update is ON and a column was edited, triggering re-enrichment.
Fix: Go to Table Settings and toggle auto-update OFF at the table level. Then enable auto-run only on specific columns that need it. The table-level setting is the parent: if OFF, no columns auto-run.
Symptom: 429 Too Many Requests when sending data via webhook.
Cause: Explorer plan has a 400 records/hour throttle.
Fix:
// Add delay between webhook submissions
async function sendWithThrottle(rows: any[], webhookUrl: string) {
for (const row of rows) {
const res = await fetch(webhookUrl, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(row),
});
if (res.status === 429) {
const retryAfter = parseInt(res.headers.get('Retry-After') || '60');
console.log(`Rate limited. Waiting ${retryAfter}s...`);
await new Promise(r => setTimeout(r, retryAfter * 1000));
}
await new Promise(r => setTimeout(r, 250)); // 250ms between requests
}
}
Symptom: Same contact appears multiple times in HubSpot/Salesforce.
Cause: No deduplication key configured in the CRM push action.
Fix: When configuring the CRM action column, use email as the unique identifier and select Update existing record if found rather than always creating new.
Symptom: Data appears in wrong columns after CSV import.
Cause: CSV headers don't match Clay column names exactly.
Fix: Normalize headers before import: trim whitespace, match case exactly. "Company Name" and "company_name" are treated as different columns.
Symptom: Formula column displays #ERROR or #REF.
Cause: Column name referenced in formula was renamed or deleted.
Fix: Edit the formula column and update all column references to match current names. Clay formulas reference columns by their display name (case-sensitive).
| Symptom | Quick Check | Likely Fix |
|---|---|---|
| Red cell indicator | Click cell for error detail | Fix API config or input data |
| Empty enrichment | Check provider connection | Reconnect in Settings > Connections |
| No new rows from webhook | Test webhook URL with curl | Re-create webhook source |
| Credits depleting fast | Check waterfall depth | Reduce to 2 providers, add conditions |
For systematic debugging, see clay-debug-bundle.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).