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 catalog.	Hit `/v1/meta/fields`, pick valid names.
`fields_too_many`	400	Resolved field set (post-preset-expansion) exceeds 50.	Drop the preset, split into multiple calls, or remove explicit fields.
`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 credits are refunded (best-effort — the refund is fail-open, so in the rare case our counter store is unreachable at that moment the charge can stick). 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/lookup`, `/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`: resolved only to a ZIP/city/county/state centroid, not a property. `/v1/lookup` returns this as a `no_match` disposition (`reason: "address_too_coarse"`), not this HTTP error; `/v1/field-requests` returns it as a 422 (the location is one field of a larger body) — see each endpoint’s page.	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`, `/v1/lookup`: the provider returned 5xx or dropped the connection.	Retry after `Retry-After` (2 s).
`geocode_timeout`	504	`/v1/geocode`, `/v1/fetch`, `/v1/ask`, `/v1/lookup`: 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`, `/v1/lookup`: 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`, `/v1/lookup`: 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.
`resolve_coord_bounds`	422	`/v1/lookup` only: coordinate is outside any plausible bound, including a swapped-lat/lng pair.	Check your lat/lng order.
`resolve_invalid_input`	422	`/v1/lookup` only: input didn’t parse as an address, `"lat,lng"` coordinate, or APN-shaped token.	Fix the input format.
`resolve_busy`	429	`/v1/lookup` only: its own per-worker overload gate (separate from `geocode_busy`).	Retry after `Retry-After` (3 s).
`resolve_timeout`	504	`/v1/lookup` only: did not complete within the endpoint’s deadline (geocode leg + parcel leg + enrichment).	Retry after `Retry-After` (5 s).
`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 — and note it IS billed, since it is raised after metering.
`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.	Retry after `Retry-After` (3600 s).
`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.	Retry with backoff.
`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).	Retry with backoff.
`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.	Retry with backoff. Persisting is worth reporting: for coordinate-only input this shape shouldn’t occur.
`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`.	Retry with backoff; a smaller request (fewer origins × destinations) will 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`.

Billing and rate limits

Both apply to every metered endpoint, and both are raised by the shared admission gate before any work is done — so a 402 or a 429 is never billed.

`error`	HTTP	Meaning	What to do
`credits_exhausted`	402	The account cannot spend the credits this request costs.	Read the body before reacting — the same code covers three different situations (below).
`rate_limited`	429	More requests per minute than the plan allows. `detail` carries `plan`, `limit_rpm`, and `retry_after_s`.	Retry after `Retry-After`.

A 402 body distinguishes its three causes so a client can route each one correctly instead of treating them all as “out of credits”:

Field	When it matters
`self_imposed_limit`	Non-null when your own monthly spend limit stopped the request, not the plan allowance. Upgrading changes nothing; raise or clear the limit in account settings.
`shared_pool_exhausted`	`true` when only per-record (parcel) calls are refused. Ordinary fields still work — retry the non-parcel half of the job rather than treating the account as dead.
neither set	The plan’s monthly allowance is genuinely spent. `resets_at` gives the reset instant, `upgrade_url` the remedy.

Every 402 also carries plan, used, included, limit, and resets_at, so the numbers reconcile against the dashboard. Every finite plan hard-stops and no tier carries overage — see Pricing. Authentication and account-route failures (401 auth_*, 403, 429 rate_limited) use the same detail shape — the full table lives on the Authentication page. Unhandled server exceptions return a plain 500 Internal Server Error (no structured detail body, and no X-Request-ID response header — the framework default, since the error bypasses the header middleware). The server-side log line still carries the request ID, so send your own X-Request-ID request header if you need to correlate a 500.

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-field request.
curl -s -i https://api.mireye.com/v1/fetch -d @big-request.json

HTTP/1.1 400 Bad Request

{
  "detail": {
    "error": "fields_too_many",
    "message": "Requested 60 fields; max is 50.",
    "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.

Ask

Fetch

Runs

Sites

Resolve

Catalog

Reference

Error code reference

Billing and rate limits

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

​Error code reference

​Billing and rate limits

​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

Error code reference

Billing and rate limits

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