Guides

Errors

Every error has the same shape, on every endpoint:

JSON

{
  "error": {
    "code": "insufficient_credits",
    "message": "This job needs up to 120 credits, but your account has 80.",
    "docs_url": "https://moleman.io/docs/errors#insufficient_credits"
  }
}

code never changes; build your logic on it. message is for people and may get clearer over time.
invalid_request also has details: every problem with its path, for example { "path": "body.rows.0.website", "message": "Too long" }.
Nothing is charged for a request that ends in an error.

All codes

`missing_api_key`

HTTP 401. The request has no API key.

What to do: Send the header Authorization: Bearer . Keys are on the API page in the app.

`invalid_api_key`

HTTP 401. The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted).

What to do: Copy the whole key again. It starts with mm_live_ or mm_test_. If you lost it, create a new one; we cannot show it again.

`revoked_api_key`

HTTP 401. The API key was revoked on the API page. Revoking takes effect at once.

What to do: Create a new key on the API page and use that one.

`wrong_key_mode`

HTTP 403. A test key asked for something made with a live key, or the other way round. Test and live data never mix.

What to do: Use a key of the same kind (mm_test_ or mm_live_) that created the job or list.

`invalid_request`

HTTP 400. A parameter is missing, has the wrong type or is out of range. details lists every problem with its path.

What to do: Fix the parameters named in details (see the endpoint page for the allowed values).

`invalid_json`

HTTP 400. The body is not valid JSON.

What to do: Send a JSON body with the header Content-Type: application/json.

`invalid_cursor`

HTTP 400. The cursor is not one we gave out (they are opaque; do not build them yourself).

What to do: Start again without cursor, then pass the nextCursor of each page unchanged.

`invalid_webhook_url`

HTTP 400. The webhook URL is not a public https address (private networks and other schemes are refused).

What to do: Use a public https URL, for example the one your Make, Zapier or n8n webhook trigger gives you.

`no_eligible_rows`

HTTP 400. None of the rows can run this action (for example: no website or domain to find an email for, or no email to check).

What to do: Check the rows: find-contacts needs a website or domain, verify needs an email, deep-search needs a company or website.

`insufficient_credits`

HTTP 402. The account has fewer credits than this request could use at most. We hold the maximum while the job runs and give back what it does not use.

What to do: Buy credits or pick a plan in the app, or send fewer rows. GET /api/v1/account shows your credits.

`not_found`

HTTP 404. The job or list does not exist, belongs to another account, or was deleted.

What to do: Check the id. Lists you deleted, and results older than 30 days that were removed, cannot come back.

`place_not_found`

HTTP 404. We could not find the place you searched in.

What to do: Use a city, county, state or ZIP / post code that exists in the country you sent.

`route_not_found`

HTTP 404. There is no endpoint at this path with this method.

What to do: Check the path and method against the reference. All endpoints start with /api/v1/.

`idempotency_in_progress`

HTTP 409. A request with the same Idempotency-Key is still running.

What to do: Wait a moment and send it again with the same key; you then get the first answer.

`payload_too_large`

HTTP 413. The body is larger than 20 MB.

What to do: Send fewer rows per request (up to 50,000 rows; 10,000 for deep-search).

`unsupported_media_type`

HTTP 415. The body is not JSON.

What to do: Send Content-Type: application/json.

`idempotency_key_reused`

HTTP 422. The Idempotency-Key was already used in the last 24 hours with a different request.

What to do: Use a new key for every new request. Reuse a key only to retry exactly the same request.

`rate_limited`

HTTP 429. More than 120 requests in one minute with this key.

What to do: Wait for the number of seconds in the Retry-After header, then go on. Big lists go in one request, not one request per row.

`server_error`

HTTP 500. Something broke on our side. Nothing was charged for it.

What to do: Retry with the same Idempotency-Key after a few seconds. If it keeps happening, write to us.

`search_unavailable`

HTTP 503. Business search is not available right now.

What to do: Try again in a few minutes.