Errors and warnings

Read a failure and a partial answer.

The error envelope

The error envelope. Every failure carries it, and the shape is frozen. Every failure also carries a `request_id`. Send the request_id to support@leadmcp.ai.

okbooleanrequired

False on every failure response.

request_idstringrequired

The id of this request. Send the request_id to support@leadmcp.ai.

releasestringoptional

The build id that served this response, when one served it.

errorobjectrequired

The failure itself.

Show child attributes

codeErrorCode (slug)required

The closed, published error code list. Codes are dotted noun.reason. We add codes and never repurpose one. account.suspended (403): an admin suspended the account, or a payment failed. After an admin suspension, contact support@leadmcp.ai. After a failed payment, update the card in Billing; spending calls are refused until a payment succeeds.

request.invalidfilter.unknown_keyfilter.unknown_valuefilter.rejectedcursor.expiredenrich.mode_unavailableenrich.too_many_inputsauth.invalid_keyaccount.suspendedcontact_credits.exhaustedpremium_credits.exhaustedcolumn.not_foundexport.not_foundalert.not_foundalert.busycollect.not_foundplan.requiredexport.expiredexport.runningexport.no_matchesrate.limiteddata.unavailablequery.timeoutsignals.below_minimumalerts.limit_reachedauth.oauth_requiredkey.limit_reachedkey.not_found

messagestringrequired

One sentence that states what failed.

hintstringoptional

The fix, named. On a closed list value it prints every allowed slug.

fieldstringoptional

The dotted path of the offending field, for example filter.country.

detailsContactCreditsExhaustedDetails or PremiumCreditsExhaustedDetails or SignalsBelowMinimumDetailsoptional

Structured error details: contact_credits.exhausted carries ContactCreditsExhaustedDetails, premium_credits.exhausted carries PremiumCreditsExhaustedDetails, and signals.below_minimum carries SignalsBelowMinimumDetails; hint and field stay beside details on error.

Show child attributes

ContactCreditsExhaustedDetailsContactCreditsExhaustedDetailsoptional

Details for contact_credits.exhausted.

Show child attributes

bindingenumrequired

The contact credit window whose cap is spent.

daymonth

resets_atstringrequired

The RFC 3339 reset time, or 9999-12-31T23:59:59.000Z for the free plan's lifetime pool.

PremiumCreditsExhaustedDetailsPremiumCreditsExhaustedDetailsoptional

Details for premium_credits.exhausted.

Show child attributes

requiredintegerrequired

The premium credits required for this request.

availableintegerrequired

The premium credits still available this month.

allowanceintegerrequired

The monthly premium credit allowance on the account.

resets_atstringrequired

The RFC 3339 time when the premium credit allowance resets.

upgrade_urlstringrequired

The billing URL where the account owner can raise the premium credit tier.

SignalsBelowMinimumDetailsSignalsBelowMinimumDetailsoptional

Details for signals.below_minimum.

Show child attributes

followersintegerrequired

The number of followers on the requested company page.

quotaQuotaoptional

present when the account is known; absent for failures before the account is identified (for example a missing or invalid key)

Show child attributes

planstringrequired

The plan slug this account is on. It names the caps; read the numbers themselves from GET /account.

contact_credits_usedintegerrequired

The contact credits this request spent. A count, a schema read or a miss spends zero.

month_remainingintegerrequired

The contact credits left in the current billing month. A paid plan's month starts on its billing date each month; without a subscription it is the UTC calendar month. On the free plan, the contact credits left in the lifetime pool; the pool has no window.

today_remainingintegerrequired

The contact credits left in the current UTC day. On the free plan, the same number as month_remaining.

bindingenumrequired

The window that runs out first at the current pace. On the free plan, always month.

monthday

resets_atstringrequired

The RFC 3339 UTC time at which the binding window resets. On the free plan the pool never resets, and the field is 9999-12-31T23:59:59.000Z.

Error codes

Code	Status	Meaning
`request.invalid`	400	An empty normalized name returns 400 request.invalid.
`filter.unknown_key`	400	Fields resolve against `GET /contacts/schema`, case-insensitively, and an unknown field returns 400 filter.unknown_key.
`filter.unknown_value`	400	Unknown values return 400 filter.unknown_value with allowed values and a hint to GET /contacts/schema/country/values.
`filter.rejected`	422	The filter was rejected before it ran: more than 32 predicates, deeper than 4, more than 25 leaves, more than 1,000 domains or company names, more than 50 values in another list, a leading wildcard in a where leaf, a leading or trailing wildcard in title_query, an operator, value type or shape the column does not take, a leaf other than exists with no value, or an empty `and` or `or` group.
`cursor.expired`	400	A cursor minted on an earlier build returns 400 cursor.expired, and the caller starts the search again.
`enrich.mode_unavailable`	400	Sending true returns 400 enrich.mode_unavailable.
`enrich.too_many_inputs`	400	More than 100 enrichment inputs return 400 enrich.too_many_inputs with the hint: Send at most 100 inputs per call; split larger lists into batches.
`auth.invalid_key`	401	The credential is missing, unknown or revoked.
`account.suspended`	403	`account.suspended` (403): an admin suspended the account, or a payment failed.
`contact_credits.exhausted`	402	The daily or the monthly contact credit cap is spent, or the free plan's lifetime pool is.
`premium_credits.exhausted`	402	Details for premium_credits.exhausted.
`column.not_found`	404	The id or the column does not exist, or the row was opted out.
`export.not_found`	404	The id or the column does not exist, or the row was opted out.
`alert.not_found`	404	Unknown alert id or an alert belonging to another account.
`alert.busy`	409	The alert already has a queued or running job.
`collect.not_found`	404	Unknown collect job id, an alert run, or a job of another account.
`plan.required`	403	Creating alerts requires a paid plan (plan.required).
`export.expired`	410	The export file has expired or is no longer available.
`export.running`	409	One export already runs on this account.
`export.no_matches`	400	A filter that matches nothing is refused with 400 export.no_matches, free, and no job is created.
`rate.limited`	429	The key passed 300 requests a minute or 2 concurrent requests.
`data.unavailable`	503	The data is unavailable for a short time.
`query.timeout`	504	The query passed its time budget and was stopped.
`signals.below_minimum`	400	Details for signals.below_minimum.
`alerts.limit_reached`	403	Accounts may have at most 100 active alerts (alerts.limit_reached).
`auth.oauth_required`	403	The request is signed with an API key.
`key.limit_reached`	409	The account already has its one active API key.
`key.not_found`	404	No active API key with this id on this account.

Warning codes

A warning rides on a success. The status stays 200.

Code	Status	Meaning
`count_unavailable`	200	A null count carries a count_unavailable warning.
`no_rows`	200	On zero rows the response carries a `no_rows` warning that names the keys applied.
`export_truncated`	200	The export_truncated warning names the reason and the reset time.
`duplicate_work_email`	200	When two contacts share a work email, the later `last_updated` wins and a `duplicate_work_email` warning says so.
`duplicate_linkedin`	200	When two contacts share a LinkedIn slug, the later `last_updated` wins and a `duplicate_linkedin` warning says so.
`off_domain`	200	A person we hold at another employer, or with no employer domain, answers `matched: false` with `off_domain: true`, costs nothing, and is listed on an `off_domain` warning.
`deprecated`	200	A field, a key or a code is on its way out. It is removed no earlier than six months after this warning first appears.
`max_followers_missing`	200	Without max_followers, a company job asks for at most the premium credits available and adds a max_followers_missing warning.

Docs for agents: llms.txt