API
Errors
Error shapes and status codes across the LeadMarina API.
| 400 | Missing/invalid params (no query, unknown location, bad domain). |
| 401 | Missing, invalid, or revoked API key. |
| 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 not found (or not yours). |
| 429 | Transient — too many requests, too many searches in flight, or the hourly window (the message names the limit). Safe to retry after the Retry-After header or once a running search finishes. |
| 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. |
| 502 | Upstream data provider error — retry. |
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." }