API

Errors

Error shapes and status codes across the LeadMarina API.

400	The request can't run as sent: missing or invalid params (no query, unknown location, bad domain), a body that isn't a JSON object, a filter, cursor or destination the API can't use, or a destination that isn't connected or set up yet. The message says which.
401	Missing, invalid, or revoked API key. Only ever a verdict on the key: a key we couldn't check just then is never answered with 401.
402	Nothing to spend until something changes: the balance is empty, or the plan's 7-day (or daily) allowance is used up. Do not retry — the message names when the allowance resets.
404	Search or automation not found (or not yours).
429	A limit was reached; the message names it. The per-minute limits and searches in flight are transient: retry after the Retry-After header when one is sent, otherwise after a minute or once a running search finishes. The rolling 24-hour limits are not: the search and city limits name the time the next one fits (up to a day away), and each enrichment request frees up 24 hours after it was made, so wait rather than retrying. A search needing more cities than the whole daily budget never fits: split it.
409	The action does not apply to the search's current stage — e.g. cancelling a search that is already running or finished. The message says which.
500	Something failed on our side, not in your request — for example a read we couldn't complete, or an export the destination or storage refused. Retry shortly. Most messages say whether anything changed, and an export's carries a ref to quote to support.
502	Upstream data provider error — retry.
503	A temporary problem on our side: the database, the key check or a city lookup didn't answer just then. Your key is fine and nothing was charged, sent or saved — retry after the number of seconds in the Retry-After header.

json

{ "error": "You're out of leads. Top up to run another search." }

// On a plan with no monthly quota the 402 names the period instead:
{ "error": "You've reached your limit of 210,000 leads for this 7-day period. The full allowance comes back at the start of your next period — your dashboard shows exactly when. Get in touch if you need a higher limit." }

API

Errors

Error shapes and status codes across the LeadMarina API.

API

Errors

Error shapes and status codes across the LeadMarina API.

400	The request can't run as sent: missing or invalid params (no query, unknown location, bad domain), a body that isn't a JSON object, a filter, cursor or destination the API can't use, or a destination that isn't connected or set up yet. The message says which.
401	Missing, invalid, or revoked API key. Only ever a verdict on the key: a key we couldn't check just then is never answered with 401.
402	Nothing to spend until something changes: the balance is empty, or the plan's 7-day (or daily) allowance is used up. Do not retry — the message names when the allowance resets.
404	Search or automation not found (or not yours).
429	A limit was reached; the message names it. The per-minute limits and searches in flight are transient: retry after the Retry-After header when one is sent, otherwise after a minute or once a running search finishes. The rolling 24-hour limits are not: the search and city limits name the time the next one fits (up to a day away), and each enrichment request frees up 24 hours after it was made, so wait rather than retrying. A search needing more cities than the whole daily budget never fits: split it.
409	The action does not apply to the search's current stage — e.g. cancelling a search that is already running or finished. The message says which.
500	Something failed on our side, not in your request — for example a read we couldn't complete, or an export the destination or storage refused. Retry shortly. Most messages say whether anything changed, and an export's carries a ref to quote to support.
502	Upstream data provider error — retry.
503	A temporary problem on our side: the database, the key check or a city lookup didn't answer just then. Your key is fine and nothing was charged, sent or saved — retry after the number of seconds in the Retry-After header.

json

{ "error": "You're out of leads. Top up to run another search." }

// On a plan with no monthly quota the 402 names the period instead:
{ "error": "You've reached your limit of 210,000 leads for this 7-day period. The full allowance comes back at the start of your next period — your dashboard shows exactly when. Get in touch if you need a higher limit." }