Map Image API / API reference / Errors

Error codes

Every error from https://api.ultimaps.com/v1 is an RFC 9457 application/problem+json document. Branch on the stable code field. detail is human-readable and may change. Responses can carry extensions: errors[] (per-field validation details with region-key suggestions), suggestions[], upgrade_url, signup_url, quota_resets_at, and a Retry-After header on 429s.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://ultimaps.com/docs/api/errors#validation_error",
  "title": "Request validation failed",
  "status": 400,
  "code": "validation_error",
  "detail": "1 region key(s) did not match any region of map \"united-states\".",
  "errors": [
    { "param": "Texassss", "message": "\"Texassss\" doesn't match any region of map \"united-states\".", "suggestions": ["Texas (state-FIPS-48)"] }
  ]
}

invalid_region_id400 · Invalid region identifier · not retryable

A region key is malformed. Use ids, ISO codes or names from GET /v1/maps/{mapId}.

validation_error400 · Request validation failed · not retryable

The body (or the GET `spec` parameter) failed validation. `errors[]` names each offending field in `param` with a message and, for region keys, `suggestions`. Fix the request and retry.

unauthorized401 · Unauthorized · not retryable

The key is missing on a keyed-only endpoint, malformed, revoked or expired. A present-but-invalid key never falls back to the keyless tier. Render endpoints accept requests with no key at all.

monthly_quota_exceeded402 · Monthly quota exceeded · not retryable

A billing state, not a transient error, so never auto-retry. `quota_resets_at` is the first of next month (UTC), and `upgrade_url` leads to a bigger plan.

plan_upgrade_required403 · Plan upgrade required · not retryable

The request needs a higher tier: SVG without a Pro key, a keyless request over 1600×1600 px at scale 1, or a free-key request over 1600×1600 px at scale 2. It costs no quota. `upgrade_url` and `signup_url` say where to go.

not_found404 · Not found · not retryable

No such endpoint under /v1. Check the path against the OpenAPI document.

unknown_map404 · Unknown map · not retryable

No map with that `mapId` is available to you. `suggestions[]` lists close ids, and GET /v1/maps has the full catalog.

render_expired410 · Render expired · not retryable

A hosted render URL has expired. Reserved for future hosted outputs. Render again.

payload_too_large413 · Payload too large · not retryable

The JSON body exceeds 2 MB. Trim `choropleth.values`, `categories.values` or `regions`, or split the job.

concurrency_limit_reached429 · Concurrency limit reached · retryable

Too many renders in flight for this key or IP, or the engine queue is full. Retry after `Retry-After` seconds.

rate_limit_exceeded429 · Rate limit exceeded · retryable

Per-minute limit, per-hour limit or daily cap reached. Wait `Retry-After` seconds and retry.

internal_error500 · Internal error · retryable

Something unexpected happened on our side, and it has been reported. Safe to retry with backoff.

render_failed502 · Render failed · retryable

The render engine could not produce an image. Retry once with backoff. If it persists, contact support with the `X-Ultimaps-Render-Id`.

render_timeout504 · Render timed out · retryable

The render exceeded the 30-second budget. Reduce the canvas, the data volume or the number of pins and retry.

Retry policy

Retry 429, 500, 502 and 504 with exponential backoff, honouring Retry-After when present. Never retry 400, 401, 402, 403, 404 or 413 without changing the request.

Working examples and the map catalog: the cookbook.

Machine-readable: openapi.json · llms-full.txt