Errors

All errors use standard HTTP status codes plus a structured detail object. The body shape is consistent:

{
  "detail": {
    "error": "<machine-readable error code>",
    "message": "<human-readable explanation>",
    /* …optional context fields per error code */
  }
}

Every response except unhandled 500s carries X-Request-ID. You can also send your own X-Request-ID request header — the server echoes it and binds it to its log lines, which is the reliable way to correlate even the responses that lack the header.

Error code reference

Error code	HTTP	Meaning	How to recover
`coord_out_of_bounds`	400	The coordinate is outside both supported US regions.	Accept the primary `us_envelope` from `/v1/meta/fields` or the Western Aleutian rectangle (`lat ∈ [51, 54]`, `lng ∈ [172, 180)`).
`no_fields_requested`	400	`/v1/fetch` called with neither `fields` nor `preset`.	Provide at least one of the two.
`fields_unknown`	400	One or more requested field names are not in the endpoint’s catalog.	For Fetch use `/v1/meta/fields`; for Enrich use the Enrich field reference.
`fields_too_many`	400	Fetch has more than 50 distinct explicit fields outside the chosen preset; preset members are exempt.	Remove additional explicit fields or split them into bounded requests. The MCP explicit list separately accepts at most 50 entries. Enrich has no 50-field cap.
`ask_upstream_rate_limited`	429	`/v1/ask`: the LLM API rate-limited the call.	Retry with backoff (`retryable: true`).
`ask_upstream_unreachable`	502	`/v1/ask`: could not reach the LLM API.	Retry with backoff (`retryable: true`).
`ask_upstream_error`	502	`/v1/ask`: the LLM API returned an error.	Retry only if `retryable: true` (upstream 5xx).
`ask_timeout`	504	`/v1/ask` exceeded the 110 s end-to-end deadline.	Retry; persistent timeouts mean a degraded upstream source.
`ask_answer_incomplete`	502	`/v1/ask`, `/v1/ask/stream`, `/v1/ask-site`: the model did not return a complete answer — it ran out of output budget mid-answer, or omitted a required part of it.	Retry (`retryable: true`). The condition is stochastic, so the same question usually succeeds on the next attempt. The incomplete answer is not charged; its unused reservation is released. On the streaming endpoint this arrives as a terminal `error` frame and no `final` frame, so any text already streamed should be discarded rather than shown as the answer.
`ask_question_refused`	422	`/v1/ask`, `/v1/ask/stream`, `/v1/ask-site`: the model declined to answer the question.	Do not retry (`retryable: false`) — unlike `ask_answer_incomplete` this is deterministic for the same input, so an identical retry fails identically. Rephrase the question.
`invalid_locator`	422	`/v1/fetch`, `/v1/ask`, and the MCP tools: the request gave BOTH a coordinate and an address, or neither, or only half a coordinate. `/v1/field-requests` uses the same code when an `example_locations` entry doesn’t supply exactly one of `address`, `lat`+`lng`, or `polygon`.	Send exactly one locator per location.
`address_form_unsupported`	422	`/v1/geocode`, `/v1/fetch`, `/v1/ask`, `/v1/field-requests`: the address is a PO box, carrier route (RR/HC), military APO/FPO, or general delivery — a mail destination, not a place.	Ask the user for a street address. Reformatting cannot help; these have no coordinate in principle. Costs nothing — rejected before the provider is called.
`address_not_found`	404	`/v1/geocode`, `/v1/fetch`, `/v1/ask`: the provider processed the address and has no match.	Check for a typo; do not retry.
`address_too_coarse`	404	`/v1/geocode`, `/v1/fetch`, `/v1/ask`, `/v1/enrich`: resolved only to a ZIP/city/county/state centroid, not a property. `/v1/field-requests` returns this as 422 because the location is one field of a larger body.	Ask the user for a street number. Retrying cannot help; the provider’s answer is stable.
`geocode_busy`	429	`/v1/geocode`, `/v1/fetch`, `/v1/ask`: the per-worker overload gate shed the request.	Retry after `Retry-After` (2 s).
`geocode_upstream_error`	502	`/v1/geocode`, `/v1/fetch`, `/v1/ask`: the provider returned 5xx or dropped the connection.	Retry after `Retry-After` (2 s).
`geocode_timeout`	504	`/v1/geocode`, `/v1/fetch`, `/v1/ask`: the primary provider AND the fallback both exceeded their deadlines.	Retry after `Retry-After` (5 s).
`geocode_forbidden`	503	`/v1/geocode`, `/v1/fetch`, `/v1/ask`: the geocoding provider recognized the credential but refused the request — almost always a usage/spend limit or a missing plan entitlement.	Not a bad key. Check the provider’s usage limit first; the daily cap resets at midnight EST, so `Retry-After` is an hour. The upstream’s own message is included in `message`.
`geocode_unconfigured`	503	`/v1/geocode`, `/v1/fetch`, `/v1/ask`: the service is missing its provider credential.	Not a caller problem and not retryable — report it. We deliberately do NOT degrade to the free lower-precision tier, which would look healthy while serving ~2,872 m rural error.
`invalid_request`	422	`/v1/proximity` only: the body fails the schema — a bad field, an unknown `op`, or a per-request limit (origins × destinations, address-form locators). Uses the standard error object, with pydantic’s per-field detail under `errors`.	Fix the keys named in `errors`; for a limit breach, split the request.
`unresolvable_input`	422	`/v1/proximity` only: every locator for a required role (an op’s origin(s), or `screen`’s anchors) failed to resolve. Carries `role`, `unresolved_count`, an `unresolved` sample naming each locator, what it matched instead and at what `accuracy_type`, and `caller_guidance`.	Read `unresolved` — a `place` tier means you sent a name or a bare street, so add city+state or use a coordinate. See Diagnosing `unresolvable_input`.
`unknown_set`	422	`/v1/proximity` only: `nearest`’s `set` isn’t one of the six curated sets.	Use `@airports`, `@substations`, `@power_plants`, `@rail`, `@ports`, or `@urban_areas`.
`shed_too_large`	422	`/v1/proximity` only: `labor_shed`’s geometric annulus exceeded 3,000 tracts.	Shrink `minutes`.
`proximity_request_exceeds_budget_share`	422	`/v1/proximity` only: one request would reserve more than its allowed share of the shared, fleet-wide monthly driving-matrix budget. Distinct from `proximity_budget_exhausted` — the pool has room, this single call is too big a bite of it.	Shrink the request as `message` directs: split the locator lists, or for `labor_shed` (which has no batch parameter) reduce `minutes`. `message` names the ceiling in driving calcs (currently 3,500 per request). Not retryable — the same body fails identically every time. Failed source execution is not charged.
`proximity_busy`	429	`/v1/proximity` only: its own per-worker overload gate (separate from `geocode_busy`/`resolve_busy`). Never billed.	Retry after `Retry-After` (5 s).
`proximity_budget_exhausted`	503	`/v1/proximity` only: the shared, fleet-wide monthly driving-matrix budget is exhausted. Failed source execution is not charged.	Follow the paid Proximity retry contract. A confirmed failed operation needs a new key after the budget resets; retryable responses include `Retry-After: 3600`.
`proximity_data_unavailable`	503	`/v1/proximity` only: a backing local asset (a curated set, or the labor-shed tract table) isn’t available right now.	Follow the paid Proximity retry contract; confirmed failures need a new key.
`proximity_unconfigured`	503	`/v1/proximity` only: the service is missing its routing-provider credential.	Not a caller problem and not retryable — report it.
`upstream_transient`	502	`/v1/proximity` only: the routing provider had a transient failure (5xx, connection drop, rate limit).	Follow the paid Proximity retry contract; confirmed failures need a new key.
`upstream_auth`	502	`/v1/proximity` only: the routing provider rejected the credential or the request.	Not retryable — report it.
`upstream_error`	502	`/v1/proximity` only: the catch-all for a routing-provider failure the specific codes above don’t name — a malformed distance-matrix response, or a status the provider isn’t documented to return for pre-validated coordinates.	Follow the paid Proximity retry contract. Report persistent failures.
`proximity_deadline_exceeded`	504	`/v1/proximity` only: the request exceeded the endpoint’s own deadline. Distinct from a routing-provider timeout, which stays `upstream_transient`.	Follow the paid Proximity retry contract. A smaller request (fewer origins × destinations) can also finish sooner.
`invalid_payload`	422	`/v1/field-requests` only: the body fails the schema — missing required field, limit exceeded, or an unknown key (rejected, never ignored). Unlike the rest of the API, schema errors on this endpoint use the typed `detail` shape, with pydantic’s per-field detail under `errors`.	Fix the keys named in `errors`.
`context_blob_too_large`	422	`/v1/field-requests`: `context_blob` exceeds 8 KB (UTF-8 bytes).	Shrink the blob.
`location_out_of_bounds`	422	`/v1/field-requests`: an `example_locations` coordinate is outside the US envelope — a swapped lat/lng pair is named as such.	Check coordinate order and coverage.
`invalid_geometry`	422	`/v1/field-requests`: `polygon` isn’t a GeoJSON `Polygon`/`MultiPolygon`, or has no coordinates.	Fix the geometry.
`location_unresolved`	422	`/v1/field-requests`: an address had no plausible geocode match, or its lone match was in a different city than the one named.	Supply a coordinate or a fuller address.
`idempotency_key_reused`	409	`/v1/field-requests`: the idempotency key was already used for a different payload.	Use a new key, or re-send the identical body.
`field_requests_unavailable`	503	`/v1/field-requests`: the request store is unreachable.	Retry with backoff.
`field_request_not_found`	404	`GET /v1/field-requests/{id}`: no such request under your credential (someone else’s id is also a 404, never a 403).	Check the stored `request_id`.

Agent setup errors

The HTTP onboarding endpoints use these codes. Never include an API key in an error report.

Error	HTTP	Recovery
`terms_required`	403	Accept the current Earth terms through the dashboard before creating an attempt.
`terms_unavailable`	503	Current policy or acceptance could not be verified; retry with backoff.
`onboarding_terms_changed`	409	Read and accept the current document, then start a new attempt.
`onboarding_not_found`	404	Check the attempt ID and signed-in account; other accounts’ attempts are also 404.
`onboarding_token_mismatch`	403	Use the API key issued for this exact attempt.
`account_not_eligible`	403	Sign in with an existing active, verified account.
`user_disabled`	403	The account is disabled; contact support instead of retrying setup.
`email_unverified`	403	Verify the account email before setup.
`auth_method_not_allowed`	403	Use Firebase for setup/status and the bound API key for credential validation/progress.
`onboarding_unavailable`	503	Retry with backoff; setup storage is unavailable.
`account_store_misconfigured`	503	Onboarding storage credentials need operator attention.
`rate_limited`	429	Wait for `Retry-After` before starting another setup.

Dollar billing and rate limits

Lookup and Resolve are retired. Their former resolve_* errors no longer describe active request handling; authenticated calls now return 410 endpoint_retired. Follow the migration guide.

Code	HTTP	Action
`rate_limited`	429	Respect `Retry-After`; free calls also consume request capacity.
`spend_limit_exceeded`	402	Increase the caller ceiling, add funds or change the account spending limit.
`spending_paused`	402	Resolve the account payment restriction before paid usage.
`idempotency_conflict`	409	This key belongs to another payload; recover that operation or use a new key for new work.
`operation_in_progress`	409	Retry the same key after `Retry-After`; do not create duplicate work. Also returned briefly after a completed, charged result while it is still being saved for replay.
`operation_outcome_unknown`	503	Retry the same key so billing can reconcile; do not submit a new operation.
`billing_unavailable`	503	When `retryable` is `true`, retry the same key after `Retry-After`. If the work already finished but billing could not record its charge yet, the result is held back (the body carries a `hint`, `Retry-After` is about 30 seconds): retrying the same key returns it once the charge is recorded, charged once, or ends in `operation_failed` with no charge if it could not be kept. When the body has `operation_status: "failed"` and `retryable: false`, that key ended without a billed result; a new key starts a separately billable request.
`operation_failed`	410	The operation ended without a billed result, including when completed work could not be saved; any hold is released. Correct the source problem, or use a new key, before starting new work.
`operation_not_found`	404	Check the operation ID and authenticated owner.
`result_expired`	410	The saved paid result’s retention period ended.
`result_not_retained`	410	The operation completed and was charged, but its result was not saved for replay (for example, the server stopped right after responding). Not retryable with this key. The body’s `receipt` (`operation_id`, `charged_usd`, `settled_micros`, `settled_at`) records the charge; a new key runs the work again as a separately billed request.
`endpoint_retired`	410	Replace Lookup/Resolve with Enrich, free Fetch or Geocode.

A completed result is normally saved for replay within seconds of the response. Until it is saved, a same-key retry or GET /v1/operations/{operation_id} returns 409 operation_in_progress with Retry-After. If it is still unsaved two minutes after the charge, the answer is a terminal 410 result_not_retained:

{
  "detail": {
    "error": "result_not_retained",
    "message": "This operation was charged, but its saved result was not retained. ...",
    "retryable": false,
    "operation_id": "op_…",
    "receipt": {
      "operation_id": "op_…",
      "currency": "USD",
      "charged_usd": "0.020000",
      "settled_micros": 20000,
      "settled_at": "2026-10-21T18:04:05Z"
    }
  }
}

Paid error bodies include operation_id where one has been assigned. HTTP headers also expose X-Operation-Id. Free Fetch and Geocode do not consult the wallet. Paid results and replay delivery require fresh authorization; see Authentication for terms and credential errors.

Dataset availability

Dataset permission is separate from account access and accepted terms. These errors apply to Enrich, Search, Ask, Sites and their saved results in REST and hosted MCP. They do not disable free Fetch, Geocode or driving-only operations.

Code	HTTP	Action
`dataset_withdrawn`	410	The dataset or saved result is no longer available. Do not retry that operation or handle (`retryable: false`).
`dataset_changed`	409	The dataset refreshed during execution. After this known failure, start a new operation; restart Search without its old cursor (`retryable: false`).
`dataset_control_unavailable`	503	Permission could not be verified. Retry the same idempotency key with backoff (`retryable: true`); there is no fixed `Retry-After` interval.

Responses use Cache-Control: private, no-store. A withdrawal can make an unexpired saved result or Site unavailable. Reactivation does not restore old withdrawn results. Ordinary refreshes preserve access to saved results under the same permission epoch, subject to retention and account authorization, but invalidate Search continuation cursors. During streaming, a terminal error frame replaces the final answer; discard partial text. If a permission check interrupts source work before a complete result exists, the operation ends as operation_failed; start new work only after availability is restored. If work completed before a temporary permission outage, retry the same key to recover its saved result. A delivery refusal does not itself reverse an earlier settled charge or resolve an unknown payment outcome.

Worked examples

The validation examples below need a valid token — authentication runs before request validation, so an unauthenticated call returns 401 auth_missing rather than the 400s shown.

`coord_out_of_bounds`

curl -s -i https://api.mireye.com/v1/fetch \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"lat": 10.0, "lng": -74.0, "preset": "terrain"}'

HTTP/1.1 400 Bad Request
content-type: application/json
x-request-id: req_a1b2c3d4e5f6

{
  "detail": {
    "error": "coord_out_of_bounds",
    "message": "V1 supports US coordinates only; received lat=10.0, lng=-74.0"
  }
}

`no_fields_requested`

curl -s -i https://api.mireye.com/v1/fetch \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"lat": 40.7128, "lng": -74.0060}'

HTTP/1.1 400 Bad Request

{
  "detail": {
    "error": "no_fields_requested",
    "message": "Provide `fields` and/or `preset`."
  }
}

`fields_unknown`

curl -s -i https://api.mireye.com/v1/fetch \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"lat": 40.7128, "lng": -74.0060, "fields": ["elevation_m", "slope"]}'

HTTP/1.1 400 Bad Request

{
  "detail": {
    "error": "fields_unknown",
    "message": "Unknown field names: ['elevation_m', 'slope']",
    "fields_unknown": ["elevation_m", "slope"]
  }
}

Common gotchas:

elevation_m → elevation (no unit suffix).
slope → slope_degrees (unit suffix required to disambiguate from aspect_degrees).
floodplain → within_floodplain_polygon (full predicate name).
power_plant → nearest_power_plant_name (or …_distance_m, …_primary_fuel, …).

`fields_too_many`

# Hypothetical: 60 distinct explicit fields outside any chosen preset.
curl -s -i https://api.mireye.com/v1/fetch \
  -H "X-API-Key: $MIREYE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d @big-request.json

HTTP/1.1 400 Bad Request

{
  "detail": {
    "error": "fields_too_many",
    "message": "Requested 60 explicit fields; max is 50 (preset fields are exempt).",
    "max": 50,
    "requested": 60
  }
}

Pydantic validation errors (FastAPI default)

If the request body fails schema validation (e.g. missing lat, wrong type), FastAPI’s default 422 response shape applies:

HTTP/1.1 422 Unprocessable Entity

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "lat"],
      "msg": "Field required",
      "input": {"lng": -74.0, "question": "..."}
    }
  ]
}

These are caller bugs (malformed request, not a domain-level error) and should be caught in client-side serialization. The structured loc path tells you which field needs fixing.

What is NOT an error

Partial source failures in /v1/fetch are 200 OK with a populated partial_failures array. Failed sources never cause a non-200 response. This is the honesty pattern.
Low-confidence /v1/ask answers are 200 OK with confidence: "low". We still return the answer the synthesizer wrote; the confidence bucket tells the caller how much to trust it.
An imprecise /v1/geocode coordinate is 200 OK. Only a centroid-grade result is rejected as address_too_coarse; a street-interpolated one is returned and labelled range_interpolation, and it is the caller’s job to read accuracy_type.

Reporting issues

If you hit an unexplained 500, please include:

Your X-Request-ID request header value if you set one (plain 500s don’t echo it back, but the server log line has it).
The request body (sanitized).
Approximate timestamp (UTC) and endpoint.

We’ll find the corresponding log line in Fly logs.

Parcel Search

POST /v1/search returns HTTP 422 with search_invalid_request for malformed request shapes, search_invalid_filter for unsupported fields or typed conditions, and search_limit_exceeded for result counts above the supported maximum. These errors include issues with paths and correction hints, docs_url, and request_id. An invalid, expired, or request-mismatched cursor is search_invalid_request; restart without the cursor or resend the original filters, fields and enrich value. These errors are not retryable without correcting the request. The optional enrich flag must be a JSON boolean: null, strings and numbers return 422 search_invalid_request. The filters list must include a positive state or state2 selection: eq with one two-letter code, or in with a nonempty list of codes for the 50 US states or DC. Missing state, invalid codes, an empty state list, or only negative ne state predicates return 422 search_invalid_request. County and acreage are optional; a county name, FIPS code or geometry filter does not replace the state selection. 429 search_busy, 503 search_unavailable, and 504 search_deadline_exceeded are retryable and carry Retry-After: 3. Account rate limiting can specify another delay. A deployment without the API token signing secret returns 503 search_unavailable before candidate work; /readyz reports search_cursor_key_unconfigured. A 200 response can be limited or partial; inspect completion_reason and available fields or compact enriched_fields. Missing or null outputs do not establish a negative finding; full enrichment omits failed fields from its public map. Failed enrichment retains the match and makes the response partial; timeout failures use completion_reason: "timeout". Counts and processing diagnostics remain internal. See Search for the complete contract.

Enrich

POST /v1/enrich and mireye_enrich share the same request and result contract. Supply exactly one locator: address or both lat and lng. Invalid shapes, empty fields, and unknown presets return 422. Unknown individual field IDs return 400 fields_unknown; use the Enrich field reference. Enrich has no 50-field cap. Omitting both fields and preset requests all Enrich fields, so select a small set when correcting or retrying a request. Address inputs can return the shared Geocode errors above. Account rate limits return 429 rate_limited; worker capacity returns 429 fetch_busy. Respect Retry-After (2 seconds for fetch_busy, the response’s delay for account limits). HTTP 200 is not proof that a parcel was matched or every field succeeded. Inspect parcel_match.status: ambiguous, no_match, and unavailable return an empty fields map. A matched parcel can also return fields: {}: failed fields and most null-valued fields are omitted. Standalone Enrich exposes neither field statuses nor partial_failures, error, or retryable. Retained nulls come from a temporary allowlist and can still represent missing source attributes. Neither an omitted field nor a retained null proves absence, or tells you that a retry will help. Inline Search enrichment retains its field statuses and failure details. See Enrich.

Ask

Fetch

Runs

Sites

Location utilities

Discover parcels

Catalog

Reference

Migration

Error code reference

Agent setup errors

Dollar billing and rate limits

Dataset availability

Worked examples

`coord_out_of_bounds`

`no_fields_requested`

`fields_unknown`

`fields_too_many`

Pydantic validation errors (FastAPI default)

What is NOT an error

Reporting issues

Parcel Search

Enrich

​Error code reference

​Agent setup errors

​Dollar billing and rate limits

​Dataset availability

​Worked examples

​coord_out_of_bounds

​no_fields_requested

​fields_unknown

​fields_too_many

​Pydantic validation errors (FastAPI default)

​What is NOT an error

​Reporting issues

​Parcel Search

​Enrich

Error code reference

Agent setup errors

Dollar billing and rate limits

Dataset availability

Worked examples

`coord_out_of_bounds`

`no_fields_requested`

`fields_unknown`

`fields_too_many`

Pydantic validation errors (FastAPI default)

What is NOT an error

Reporting issues

Parcel Search

Enrich