Clay Known Pitfalls

Overview

Real gotchas when using Clay's data enrichment platform. Clay's credit-based waterfall enrichment model, table-based workflow, and multi-provider data sourcing create specific failure modes.

Prerequisites

• Clay account with API access

• Understanding of waterfall enrichment logic

• Familiarity with Clay's credit billing model

Instructions

Step 1: Prevent Credit Burn from Waterfall Misconfiguration

Enable "Stop on first result" on each waterfall step. Without this, all providers run even after finding data, burning 3x credits per lookup.

Step 2: Filter Blank/Invalid Rows Before Enrichment

Clay charges credits per row processed, even if input data is blank. Validate emails contain @ , filter empty fields, and deduplicate before sending rows.

Step 3: Normalize CSV Headers Before Import

Clay auto-maps CSV columns by name. "Company Name" vs "company_name" causes silent mismatches. Normalize: strip().lower().replace(" ", "_") .

Step 4: Rate Limit API Calls

Batch rows (50 per request) with 2-second delays between batches. Handle 429 responses by reading the Retry-After header.

Step 5: Don't Read Immediately After Write

Enrichments run asynchronously. Poll with exponential backoff (up to 30s) or use webhooks instead of reading immediately after row creation.

For detailed code examples (Python and TypeScript) of each pitfall and fix, load the reference guide: Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)

Error Handling

Issue Cause Solution

Credits burning fast Waterfall not stopping on match Enable "stop on first result"

Blank enrichment results Input rows have invalid data Pre-validate before sending

Column mapping errors CSV header mismatch Normalize headers before import

429 rate limit errors Too many API calls/minute Batch requests with delays

Empty enrichment fields Reading before enrichment completes Poll with backoff or use webhooks

Resources

• Clay API Docs

• Clay Waterfall Guide

Output

• Configuration files or code changes applied to the project

• Validation report confirming correct implementation

• Summary of changes made and their rationale

See audit implementation details for output format specifications.

Examples

Basic usage: Apply clay known pitfalls to a standard project setup with default configuration options.

Advanced scenario: Customize clay known pitfalls for production environments with multiple constraints and team-specific requirements.