clay-known-pitfalls

name	clay-known-pitfalls
description	Identify and avoid the top Clay anti-patterns, gotchas, and integration mistakes. Use when reviewing Clay integrations for issues, onboarding new team members, or auditing existing Clay table configurations. Trigger with phrases like "clay mistakes", "clay anti-patterns", "clay pitfalls", "clay what not to do", "clay gotchas", "clay code review".
allowed-tools	Read, Grep
version	1.14.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","clay","audit"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Clay Known Pitfalls

Overview

Real gotchas when using Clay's data enrichment platform. These are the mistakes that cost credits, waste time, or break integrations -- learned from production experience. Each pitfall includes the exact symptom, root cause, and fix.

Prerequisites

• Active Clay account with tables configured
• Understanding of Clay's credit and enrichment model
• Experience with at least one Clay enrichment workflow

Instructions

Pitfall 1: Webhook 50K Limit Surprise

Symptom: Webhook silently stops accepting new data. No error, no notification. New rows simply don't appear.

Root cause: Each Clay webhook has a hard 50,000 submission lifetime limit. This limit persists even after deleting rows from the table.

Fix:

• Monitor webhook submission count in your application
• Create a new webhook on the same table when approaching 45K
• Use the WebhookRotator pattern from clay-load-scale
• Set up an alert at 40K submissions

---

Pitfall 2: Waterfall Burns Credits Without "Stop on First Result"

Symptom: Credits consumed at 3-5x the expected rate on waterfall enrichment columns.

Root cause: By default, waterfall enrichment may query ALL providers even after the first one finds data. You must explicitly enable "stop on first result."

Fix: In each waterfall column's settings, ensure the stop condition is configured. Without it, a 5-provider email waterfall costs 10-15 credits per row instead of 2-3.

---

Pitfall 3: Personal Email Domains Waste Credits

Symptom: Company enrichment returns empty for 30-50% of rows.

Root cause: Rows contain gmail.com, yahoo.com, hotmail.com domains. Clay's company enrichment can't match personal email domains to companies.

Fix:

const PERSONAL_DOMAINS = new Set([
  'gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com',
  'icloud.com', 'aol.com', , ,
]);

 () {
   rows.( {
     domain = r.?.();
     (.(domain)) {
      .();
       ;
    }
     ;
  });
}