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.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
compatible-with	claude-code, codex, openclaw
tags	["saas","clay","audit"]

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)) {
      .();
       ;
    }
     ;
  });
}