Errors and rate limits

Errors use an HTTP status code and a JSON detail string.

{
  "detail": "This search needs 1,000 credits, but 700 remain."
}

Status codes

Status	Meaning	Retry guidance
`200`	Read succeeded.	None.
`202`	Search or enrichment accepted, or an idempotent retry returned its existing job.	Store `job_id` and poll the matching endpoint family.
`401`	Missing, invalid, or revoked API key.	Fix or rotate the key; do not retry blindly.
`402`	Insufficient credits or inactive paid subscription.	Reduce the request if the balance allows, or update the plan.
`403`	Free, plan, or product job-size limit exceeded.	Lower `maxResults` or the number of submitted businesses.
`404`	Search or enrichment job not found for the authenticated account.	Verify the job ID, endpoint family, and API-key owner.
`409`	Idempotency key was reused with a different request.	Restore the original body or use a new key for a genuinely new job.
`422`	Query, path, or JSON body validation failed, including `maxResults` below 100.	Correct the request fields.
`428`	Production job creation omitted `Idempotency-Key`.	Add a stable key and retry.
`429`	Request limit or active-search concurrency limit reached.	Honor `Retry-After`; retry with backoff and jitter.
`503`	A required production service is unavailable.	Retry later with the same idempotency key for creation.

Request rate limit

The account receives 1,000 API requests per rolling 60 seconds, shared across every API key. There is no daily or monthly request cap. Creating another key does not increase throughput. Successful responses include:

RateLimit-Policy: "mapsdata-api";q=1000;w=60
RateLimit: "mapsdata-api";r=998;t=60
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 60

When the limit is exhausted, the API returns 429 Too Many Requests plus Retry-After.

Active-job concurrency

Search and enrichment creation share a separate account-wide active-job limit. When all slots are occupied, the API returns 429 with Retry-After: 10. Continue polling existing jobs; submit the next job after one becomes terminal.

Retry policy

Use exponential backoff with jitter for 429 and transient 5xx responses. Cap retries and surface persistent failures. For POST /searches and POST /enrichments, every retry of the same logical operation must preserve both the request body and Idempotency-Key.

Getting started

Endpoints

Reference

Status codes

Request rate limit

Active-job concurrency

Retry policy

​Status codes

​Request rate limit

​Active-job concurrency

​Retry policy

Status codes

Request rate limit

Active-job concurrency

Retry policy