Mireye

/api-reference/errors

Errors

Structured error codes returned by /v1/* endpoints.

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

​ Error code reference

​ Worked examples

​ 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"}'

​ 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}'

​ 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"]}'
  • 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

​ Pydantic validation errors (FastAPI default)

HTTP
HTTP/1.1 422 Unprocessable Entity

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

​ 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

  • 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.