--- title: "Error codes buyers should expect from a lookup API – Invenitor" description: "Error codes buyers should expect from a contact lookup API: 401, 429, 4xx validation, 5xx – and why timeouts/errors should not spend credits." url: https://invenitor.com/blog/error-codes-buyers-should-expect-from-a-lookup-api agents: https://invenitor.com/llms.txt mcp: https://api.invenitor.com/mcp --- [Blog](https://invenitor.com/blog) Oct 27, 2026 · 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. On this page 1. [Error families buyers should expect](#error-families-buyers-should-expect) 2. [Empty is not an error](#empty-is-not-an-error) 3. [Production hygiene around errors](#production-hygiene-around-errors) 4. [Agents must share the same codes](#agents-must-share-the-same-codes) 5. [Commercial and trust angle](#commercial-and-trust-angle) 6. [What should you do next?](#what-should-you-do-next) 7. [Procurement one-liner](#procurement-one-liner) 8. [Client mapping worksheet](#client-mapping-worksheet) 9. [Anti-pattern](#anti-pattern) 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](https://invenitor.com/blog/linkedin-github-contact-lookup-api). Keys: [Rate Limits and Keys](https://invenitor.com/blog/rate-limits-and-keys-operating-a-contact-lookup-api-in). ## 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](https://invenitor.com/blog/what-are-api-credits-in-enrichment-products). Pay-per-lookup: [What Is Pay-Per-Lookup Pricing?](https://invenitor.com/blog/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](https://invenitor.com/blog/when-we-have-them-writing-honest-marketing-for-contact-apis). 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 – , [Claude / Cursor Agents](https://invenitor.com/blog/claude-cursor-agents-calling-a-contact-lookup-mcp-endpoint), [Agent-Readable Docs](https://invenitor.com/blog/agent-readable-docs-why-mcp-md-matters-for-contact-apis), ## Commercial and trust angle Demand written semantics before you buy – [Trust Checklist](https://invenitor.com/blog/trust-checklist-before-you-buy-any-contact-api). Price on found outcomes – , [25 to 1,000 Credits](https://invenitor.com/blog/25-to-1-000-credits-choosing-an-inr-pack-size). Layer: [Contact Lookup API vs CRM vs Sequencer](https://invenitor.com/blog/contact-lookup-api-vs-crm-vs-sequencer-pick-the-right). Category: [What a Contact Lookup API Actually Does](https://invenitor.com/blog/what-is-a-contact-lookup-api). ## What should you do next? Open . 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 . ## 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](https://invenitor.com/blog/what-are-api-credits-in-enrichment-products). Pay-per-lookup: [What Is Pay-Per-Lookup Pricing?](https://invenitor.com/blog/what-is-pay-per-lookup-pricing). Trust: [Trust Checklist](https://invenitor.com/blog/trust-checklist-before-you-buy-any-contact-api). Marketing: [When We Have Them](https://invenitor.com/blog/when-we-have-them-writing-honest-marketing-for-contact-apis). Hub: [LinkedIn or GitHub Profile URL → Contact Lookup API](https://invenitor.com/blog/linkedin-github-contact-lookup-api). Keys: [Rate Limits and Keys](https://invenitor.com/blog/rate-limits-and-keys-operating-a-contact-lookup-api-in). Agents: , [Claude / Cursor Agents](https://invenitor.com/blog/claude-cursor-agents-calling-a-contact-lookup-mcp-endpoint), [Agent-Readable Docs](https://invenitor.com/blog/agent-readable-docs-why-mcp-md-matters-for-contact-apis), Packs: [25 to 1,000 Credits](https://invenitor.com/blog/25-to-1-000-credits-choosing-an-inr-pack-size). Category: [What a Contact Lookup API Actually Does](https://invenitor.com/blog/what-is-a-contact-lookup-api). · . ## 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. ## Find the person you need Describe who you need in one sentence. Your first search is free, and you pay only for contacts we find [Find people free](https://invenitor.com/login?from=https%3A%2F%2Fpeople.invenitor.com%2Fsearch&x=w7&q=c5&z=g1)[See pricing](https://invenitor.com/pricing?x=w7&q=c5&z=g2) ## Keep reading - [Nov 3, 2026 · APINames help too: How optional full name improves lookup requestsNames help too: how optional full name improves lookup requests – URL remains primary; name is a soft hint; empties stay empty under coverage.](https://invenitor.com/blog/names-help-too-how-optional-full-name-improves-lookup-requests) - [Oct 19, 2026 · APIRate limits and keys: Operating a contact lookup API in productionRate limits and keys: operating a contact lookup API in production – key hygiene, 429 backoff, and found-only credits when enrichment is live.](https://invenitor.com/blog/rate-limits-and-keys-operating-a-contact-lookup-api-in) - [Oct 12, 2026 · APIContact lookup API vs CRM vs sequencer: Pick the right layerContact lookup API vs CRM vs sequencer: pick the right layer – find contacts from profile URLs without buying a sales cloud or dialer stack.](https://invenitor.com/blog/contact-lookup-api-vs-crm-vs-sequencer-pick-the-right)