> ## Documentation Index
> Fetch the complete documentation index at: https://www.mapsdata.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and rate limits

> Handle Mapsdata API errors, retries, concurrency, and account-wide request limits.

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

```json theme={null}
{
  "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:

```text theme={null}
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`.