Rate Limits and Keys: Operating a Contact Lookup API in Production
Rate limits and keys: operating a contact lookup API in production – key hygiene, 429 backoff, and found-only credits when enrichment is live.
Shipping a contact lookup into production is less about a demo cURL and more about keys, quotas, and failure modes. Hiring products that bolt enrichment on day one often leak keys in browser bundles, retry forever on 429, or treat every HTTP call as a billable event. Operating Invenitor well means the opposite: Connecting people; a lookup API, not a sales cloud and production hygiene.
Hub: LinkedIn or GitHub Profile URL → Contact Lookup API. GitHub spoke: GitHub Profile URL Contact Lookup. Layer: Contact Lookup API vs CRM vs Sequencer. REST guide: REST Enrichment Inside a Hiring Product: Auth, Credits, Rate Limits.
Keys: store, rotate, scope
| Practice | Do | Don't |
|---|---|---|
| Storage | Server env / secret manager | Frontend bundle, public repo |
| Rotation | Rotate on staff exit and quarterly | Share one eternal key in Slack |
| Scope | One key per environment | Same key for staging + prod |
Architecture: Adding Contact Lookup to an ATS. Sync without webhooks: Webhook-Free Enrichment. Docs: /docs.
Rate limits: design for 429
Rate limits protect shared capacity. When you hit a limit, back off with jitter – do not spin a tight retry loop that looks like abuse. Queue shortlists; process in batches. Night-shift desks: Night-Shift Freelance Recruiters. Agency bulk: Agency Desk Playbook.
Credits are not the same as HTTP calls
Demand that contract in writing – What Are API Credits in Enrichment Products?, What Is Pay-Per-Lookup Pricing?. Soft mesh: coverage varies; we do not publish hit-rate percentages.
Observability that hiring PMs care about
- Alert on key 401 spikes (rotation / leak).
- Alert on sustained 429 (batch size too aggressive).
- Keep primary contact fields honest.
MCP and agents share the same pool
Agents calling lookup via MCP must use the same key hygiene and credit pool as REST – /mcp.md, Claude / Cursor Agents, Agent-Readable Docs, Building a Recruiting Copilot, MCP for Recruiting Agents.
Commercial operations
INR packs, Razorpay/UPI, 30-day windows – INR Credit Packs, UPI to API Key, 25 to 1,000 Credits, /pricing. Trust: Trust Checklist Before You Buy Any Contact API. OpenAPI contract: OpenAPI Hygiene for Enrichment Endpoints.
What should you do next?
Put the key in a secret manager. Confirm ledger vs Credit B. Size a pack on /pricing. Wire agents only after /mcp.md is in the runbook.
Incident playbook (short)
401 spike: rotate key. 429 storm: cut concurrency and add jitter. Primer: What Are API Credits. Pay-per-lookup: What Is Pay-Per-Lookup Pricing?. Trust: Trust Checklist. Hub: LinkedIn or GitHub Profile URL → Contact Lookup API. Packs: 25 to 1,000 Credits. Desks: Partner Bench Sharing, Night-Shift Freelance Recruiters. Agents: /mcp.md, Building a Recruiting Copilot. OpenAPI: OpenAPI Hygiene for Enrichment Endpoints. /docs · /pricing.
Staging checklist
Separate key. Parent: Adding Contact Lookup to an ATS, Webhook-Free Enrichment. Recruiter English: Contact Enrichment Explained for Recruiters. Layer: Contact Lookup API vs CRM vs Sequencer. Commercial: INR Credit Packs, Razorpay, UPI, Cards, Wallets. Margins: Modeling Cost per Placed Candidate.
Questions
Where should API keys live?
Server-side secret storage – not browser bundles, mobile apps, or public repos.
What should we do on HTTP 429?
Back off with jitter, queue the shortlist, and reduce batch concurrency. Do not tight-loop retries.
Do rate-limit errors spend credits?
They should not.
Can staging and production share one key?
Prefer separate keys per environment so a staging leak does not burn production capacity.
How do agents affect rate limits?
MCP tools share the same pool and limits as REST – configure concurrency in the agent, not by scraping.
Where is the integration guide?
/docs for REST, /mcp.md for agents, /pricing for packs.
How does this relate to ATS architecture?
See Adding Contact Lookup to an ATS and REST Enrichment Inside a Hiring Product for auth and sync patterns.
More in this cluster
Error Codes Buyers Should Expect from a Lookup API
Error codes buyers should expect from a lookup API – auth failures, rate limits, validation, and server faults – with honest empty vs error billing semantics.
Read
OpenAPI Hygiene for Enrichment Endpoints Hiring Tools Depend On
OpenAPI hygiene for enrichment endpoints hiring tools depend on – document empties, errors, and credits so products and copilots stay honest.
Read
Webhook-Free Enrichment: Sync Patterns for Small ATS Startups
Webhook-free enrichment: sync patterns for small ATS startups – synchronous find, job queues without bolting on webhooks first.
Read