Solar Day Out Of Range

Reference · Errors

solar_day_out_of_range422

Validation · Affects all endpoints

The instant falls outside the solar day (sunrise to next sunrise), or the computed day/night span is invalid.

What this means

A calculation that partitions a solar day — planetary horas, Tribhaga thirds, or related day/night strength — was asked to evaluate a Julian Day that is not inside that day's half-open interval from local sunrise to the next local sunrise, or the ephemeris-derived sunrise/sunset geometry produced a zero or negative span. We do not invent a plausible hora or strength for an out-of-range instant.

When you'll see this

• An engine passed a JD from a different civil day than the SolarDay it was pairing it with.
• A caller built a SolarDay for date D and evaluated an instant before D's sunrise or at/after the following sunrise without resolving the containing day first.
• Sunrise, sunset, and next sunrise from the ephemeris are disordered (non-positive day or night length) for the given location and date.

Learn more about how this works

Vedic day geometry is anchored to local sunrise. Hora, Tribhaga, and related helpers require sunrise_jd <= jd < next_sunrise_jd. Silent clamping to the first or last hora would return a classically wrong lord — the same defect class as inventing 06:00/18:00 sunrise. A non-positive span means the ephemeris returned impossible ordering; that is also a hard failure, not a default index.

Example response

{
  "success": false,
  "error": "solar_day_out_of_range",
  "message": "The instant falls outside the solar day (sunrise to next sunrise), or the computed day/night span is invalid. Use an instant within that interval, or verify location and date.",
  "details": [],
  "retry_after": null,
  "doc_url": "https://docs.asterwise.com/reference/errors/solar_day_out_of_range/",
  "request_id": "req_01HXYZABCDEFGH",
  "timestamp": "2026-05-25T12:34:56Z"
}

NEW TO APIS?

Quick fix

1. Resolve the SolarDay with solar_day_containing(jd, …) before calling hora or Tribhaga helpers, rather than pairing an arbitrary civil-date day with an unrelated instant.
2. If the location is polar or near-solstice high latitude, you may hit sun_calculation_failed first — fix location/date there.
3. Retry only after correcting the instant or the day object; do not catch and substitute a default hora.

PRODUCTION ENGINEER

Recovery pattern

Treat as a client/data wiring bug when the location has a normal sunrise. Log jd, sunrise_jd, and next_sunrise_jd from the error context.

Python:

Production handler

Python

import httpx

def call_with_solar_day(url, headers, payload):
    response = httpx.post(url, headers=headers, json=payload, timeout=30)
    if response.status_code == 422:
        body = response.json()
        if body.get("error") == "solar_day_out_of_range":
            raise ValueError(body.get("message"), body.get("details"))
    response.raise_for_status()
    return response.json()

TypeScript

async function callWithSolarDay(url: string, headers: HeadersInit, payload: unknown) {
  const response = await fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(payload),
  });
  if (response.status === 422) {
    const body = await response.json();
    if (body.error === "solar_day_out_of_range") {
      throw new Error(body.message ?? "solar_day_out_of_range");
    }
  }
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

Avoid this error by

Always obtain the SolarDay from the same JD you evaluate (solar_day_containing), and keep hora/Tribhaga calls inside that interval. Do not reuse a civil-date SolarDay across midnights without re-resolving.