Dataset API Errors | Mappinest Docs

Find error codes for dataset reads, uploads, and publishing.

Error response format

Responses include error.code, error.message, and optional error.details.

Dataset revision conflict response

{
  "error": {
    "code": "DATASET_REVISION_CONFLICT",
    "message": "Dataset has changed since this revision was loaded",
    "details": {
      "currentRevision": 5
    }
  }
}

Read and authentication errors

Error code or cause	HTTP status	Description
`API_KEY_REQUIRED`	401	Send the API key through `?key=YOUR_KEY` or `X-API-Key`.
`API_KEY_FORBIDDEN`	403	Use an active API key from the owning account.
`DATASET_READ_SCOPE_REQUIRED`	403	Use a key with `datasets:read`.
`API_KEY_ORIGIN_FORBIDDEN`	403	Check allowed domains and the request `Origin`.
`DATASET_NOT_FOUND`	404	Check the dataset ID and API key owner.
`INVALID_DATASET_PAGE`	400	Use a positive `limit` within the endpoint limit.
`INVALID_DATASET_BBOX`	400	Send ordered WGS84 bounds as `minLng,minLat,maxLng,maxLat`.
`INVALID_DATASET_CURSOR`	400	Use the cursor returned unchanged by the previous page.
`DATASET_CURSOR_STALE`	409	The dataset changed. Restart pagination from the first page.

Publish and revision errors

Error code or cause	HTTP status	Description
`DATASET_IF_MATCH_REQUIRED`	428	Send the current dataset ETag in `If-Match`.
`INVALID_DATASET_IF_MATCH`	400	Send one quoted dataset ETag without the `W/` prefix.
`DATASET_ETAG_MISMATCH`	412	Use an ETag from the dataset in the request URL.
`DATASET_REVISION_CONFLICT`	409	Reload the dataset, reconcile edits, and retry with its latest ETag.
`DATASET_BUSY`	409	Wait for the active operation to finish.
`INVALID_DATASET_MUTATION_JSON`	400	Send a valid JSON mutation object.
`DATASET_MUTATION_BODY_TOO_LARGE`	413	Keep the JSON body below 32 MiB.
`UNSUPPORTED_MEDIA_TYPE`	415	Use `Content-Type: application/json`.
`DATASET_MUTATION_OPERATION_LIMIT_EXCEEDED`	413	Limit mutations to 24,000 operations and 12,000 combined adds and updates.
`FEATURE_ID_CONFLICT`	409	Choose an ID that is not already in the dataset.
`FEATURE_NOT_FOUND`	409	Reload the dataset before editing the missing feature.
`DATASET_FEATURE_LIMIT_EXCEEDED`	413	Limit the collection and combined adds/updates to 12,000 features.
`DATASET_SIZE_LIMIT_EXCEEDED`	413	Keep canonical GeoJSON below 20 MiB.

Usage and upload limits

Error code or cause	HTTP status	Description
`DAILY_UPLOAD_LIMIT`	429	Tilesets and datasets share this daily limit. Retry tomorrow or upgrade.
`DATASET_RATE_LIMIT_EXCEEDED`	429	Wait for `Retry-After` before retrying.
`DATASET_PUBLISH_LIMIT_EXCEEDED`	429	Retry after the reported delay. Dataset Studio keeps your draft.
`FREE_QUOTA_REACHED`	429	Monthly quota exhausted. Enable PAYG or upgrade in Billing.
`UNPAID_INVOICE_GRACE_EXPIRED`	402	Pay the overdue invoice in Billing to resume serving.

Retrying requests

Honor Retry-After for rate limits. Reload on conflicts and fix invalid requests before retrying.

See HTTP status codes for shared response guidance.

Error response format

Read and authentication errors

Publish and revision errors

Usage and upload limits

Retrying requests

What to read next