Errors

The error envelope

Every 4xx and 5xx response uses one envelope:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "request_id": "9f1c2e7a-7b3d-4c1e-8a0a-2f6b1c4d5e6f"
  }
}

• code — a stable, machine-readable string from the table below. Branch on this, not on the human message.
• message — a human-readable summary. Safe to log or surface; not guaranteed to be stable across releases.
• request_id — mirrors the X-Request-Id header. Quote it in support requests.

Validation errors carry details

A validation_error (HTTP 400) adds a details object mapping each rejected field to its messages, while the top-level message stays a stable generic string:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "request_id": "…",
    "details": {
      "fips": ["This field is required."],
      "page_size": ["Ensure this value is less than or equal to 500."]
    }
  }
}

Error codes

Code	HTTP	Meaning
unauthorized	401	Missing or invalid credentials.
forbidden	403	Authenticated, but not permitted.
subscription_required	402	A Pro subscription is required to use the API.
tier_upgrade_required	402	Your API add-on doesn’t include REST access (the Free add-on covers the MCP server only — upgrade to Starter or above).
usage_limit_exceeded	402	Usage cap reached; resets at the start of your next billing period.
usage_backstop_reached	402	You’ve spent your included tokens and the usage backstop is on, so access is paused rather than billing overage. Resets at the start of your next billing period. See How overage works.
validation_error	400	Invalid request parameters. Carries a details field.
unprocessable	422	The request was valid, but can’t be fulfilled for this resource — e.g. a parcel whose boundary is too complex to render as an image. Retrying won’t help.
not_found	404	The resource does not exist.
method_not_allowed	405	HTTP method not supported on this endpoint.
rate_limited	429	Too many requests — back off and retry. See Rate limits.
internal_error	500	An unexpected server error.

Errors are never billed: X-Tokens-Used is 0 on any error response.