· 9 min read · API
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 a people search and lookup API, not a sales cloud. 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. 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 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 coverage 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).
Agents must share the same codes
MCP tools should surface the same empty vs error distinction as REST – /mcp.md, Claude / Cursor Agents, Agent-Readable Docs,
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. Keys: Rate Limits and Keys. Agents: /mcp.md, Claude / Cursor Agents, Agent-Readable Docs, Packs: 25 to 1,000 Credits. Category: What a Contact Lookup API Actually Does. /docs · /pricing.
Anti-pattern
Mapping empty to HTTP 500 teaches agents to retry forever. Empty is coverage 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 – coverage 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 found-only billing 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.
