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.
Buyers integrating a contact lookup API should know which error codes mean "fix your request," which mean "back off," and which mean "try later" – and how those paths relate to credits. Confusing empty completed finds with HTTP errors is how ledgers and trust break.
Invenitor is Connecting people; a lookup API, not a sales cloud. Soft mesh coverage varies; we do not publish hit-rate percentages. Empty means not found – that is a completed find outcome, not a 5xx. Hub: LinkedIn or GitHub Profile URL → Contact Lookup API. REST guide: REST Enrichment Inside a Hiring Product. OpenAPI: OpenAPI Hygiene for Enrichment Endpoints. Keys: Rate Limits and Keys.
Error families buyers should expect
| Family | Typical signals | Client action | Credit expectation |
|---|---|---|---|
| Auth | 401 / invalid key | Rotate or fix key | Should not spend |
| Validation | 4xx bad URL / body | Fix input | Should not spend |
| Rate limit | 429 | Back off with jitter | Should not spend |
| Server / timeout | 5xx / transport fail | Retry with cap | Should not spend |
| Empty find | 200 + empty fields | Leave empty | Free under Credit B style |
Billing pillar: Credits, Empty Results, and Timeouts. Primer: What Are API Credits. Pay-per-lookup: What Is Pay-Per-Lookup Pricing?. Honesty: Empty Means Not Found.
Empty is not an error
An empty completed find says: we looked; we do not have email/phone for this profile. That is soft mesh truth – When We Have Them. Do not map empty to a retry storm. Do not invent a fill to clear a red UI badge. Primary fields: One Primary Contact, Never Invented.
Production hygiene around errors
- Log found vs empty vs error separately.
- Alert on 401 spikes (leak/rotation) and sustained 429 (batch too hot).
- Cap retries; prefer queues – Night-Shift Freelance Recruiters, Agency Desk Playbook.
- Keep keys in env – Adding Contact Lookup to an ATS, Webhook-Free Enrichment.
Agents must share the same codes
MCP tools should surface the same empty vs error distinction as REST – /mcp.md, Claude / Cursor Agents, Building a Recruiting Copilot, Agent-Readable Docs, MCP for Recruiting Agents, What Is an MCP Server for Hiring Product Teams?.
Commercial and trust angle
Demand written semantics before you buy – Trust Checklist. Price on found outcomes – /pricing, 25 to 1,000 Credits. Layer: Contact Lookup API vs CRM vs Sequencer. Category: What a Contact Lookup API Actually Does.
What should you do next?
Open /docs. Map your client's handling for 401, 429, validation, timeout, and empty. Confirm errors do not spend. Sample five free lookups. Size a pack on /pricing.
Procurement one-liner
We require documented lookup error codes with found-only credits – empties are not errors, and timeouts/errors do not spend.
Client mapping worksheet
Columns: code family | example | retry? | spend? | owner. Fill 401, validation, 429, timeout, empty. Honesty: Empty Means Not Found. Billing: Credits, Empty Results, and Timeouts. Primer: What Are API Credits. Pay-per-lookup: What Is Pay-Per-Lookup Pricing?. Trust: Trust Checklist. Marketing: When We Have Them. Hub: LinkedIn or GitHub Profile URL → Contact Lookup API. REST: REST Enrichment Inside a Hiring Product. OpenAPI: OpenAPI Hygiene. Keys: Rate Limits and Keys. ATS: Adding Contact Lookup to an ATS, Webhook-Free Enrichment. Agents: /mcp.md, Building a Recruiting Copilot, Claude / Cursor Agents, Agent-Readable Docs, Multi-Agent Hiring Pipelines. Packs: 25 to 1,000 Credits. Desks: Night-Shift Freelance Recruiters, Agency Desk Playbook. Category: What a Contact Lookup API Actually Does. Definition: What Is a Hiring Contact API?. /docs · /pricing.
Anti-pattern
Mapping empty to HTTP 500 teaches agents to retry forever. Empty is soft mesh truth – stop and leave blank.
Questions
Is an empty result an error code?
No. Empty completed finds are successful responses with no email/phone found – soft mesh truth, not a 5xx.
Should 429 responses spend credits?
No. Rate limits should not spend. Back off with jitter and reduce concurrency.
What about timeouts?
Timeouts and transport failures should not spend under honest Credit B style contracts.
How should UIs treat errors vs empties?
Separate badges. Never invent a contact to clear an empty state.
Do agents see different codes via MCP?
They should not. MCP and REST should share empty vs error semantics – see /mcp.md.
Where is OpenAPI hygiene covered?
OpenAPI Hygiene for Enrichment Endpoints – status codes, empties, credit headers.
What docs should buyers read first?
/docs, the credits pillar, rate limits and keys, and the trust checklist.
More in this cluster
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
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.
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