Ephemeris Unavailable
ephemeris_unavailable503
Astronomical calculation engine is temporarily down. Retry with backoff or fall back gracefully.
What this means
Asterwise's astrological calculations depend on the Swiss Ephemeris — a set of binary files that provide precise planetary positions for any moment in history. When this error fires, the ephemeris layer is unreachable: a file is missing on the server, file permissions are wrong, or the underlying Swiss Ephemeris library itself errored out. The request was structurally valid; we just couldn't reach the data needed to compute the answer.
When you'll see this
- A required Swiss Ephemeris file isn't installed for the requested date range (e.g.
seas_18.se1missing for an 1800-1899 birth). - Filesystem permissions blocked the API process from reading an ephemeris file (config or deploy issue on our side).
- Swiss Ephemeris raised an unrecoverable error during a planetary calculation.
- A new node has rolled out without the full ephemeris bundle and is serving a small percentage of traffic.
Learn more about how this works
Think of the ephemeris as the dataset every astrology calculation reads from — it's not optional and it's not something we can synthesize from other inputs. When it's missing, no answer is possible for the affected birth date. The good news: this almost always recovers on retry because the failures are either transient (one node misbehaving) or scoped to a narrow date range. The retry budget should be short — if the issue is a missing file, retrying for hours won't fix it.
Example response
{
"success": false,
"error": "ephemeris_unavailable",
"message": "Ephemeris calculations are temporarily unavailable. Please try again in a few minutes, or contact [email protected] if the problem persists.",
"details": [],
"retry_after": null,
"doc_url": "https://docs.asterwise.com/reference/errors/ephemeris_unavailable",
"request_id": "req_01HXYZABCDEFGH",
"timestamp": "2026-05-25T12:34:56Z"
}
- Wait 30-60 seconds and retry the request.
- If it keeps failing for the same birth date but works for others (try 1990-01-01 as a baseline), email [email protected] with the original
request_idand the birth date that fails. - Check status.asterwise.com — if there's an active ephemeris incident, we'll have posted it.
This error includes retry_after semantics implicitly — backoff for ~60 seconds, then up to 3 retries, then surface to the user. Don't hammer.
Python:
Production handler
- Python
- TypeScript
import httpx
import time
def call_with_backoff(url, headers, payload):
for attempt in range(3):
response = httpx.post(url, headers=headers, json=payload, timeout=30)
if response.status_code == 503:
body = response.json()
if body.get("error") == "ephemeris_unavailable":
time.sleep(2 ** attempt * 30) # 30s, 60s, 120s
continue
return response
raise RuntimeError("Ephemeris unavailable after 3 attempts")
async function callWithBackoff(url: string, headers: HeadersInit, payload: unknown) {
for (let attempt = 0; attempt < 3; attempt++) {
const response = await fetch(url, {
method: "POST",
headers,
body: JSON.stringify(payload),
});
if (response.status === 503) {
const body = await response.clone().json();
if (body.error === "ephemeris_unavailable") {
await new Promise((r) => setTimeout(r, Math.pow(2, attempt) * 30_000));
continue;
}
}
return response;
}
throw new Error("Ephemeris unavailable after 3 attempts");
}
Avoid this error by
- Cache successful natal chart responses on your side. The natal positions for a given birth never change — there's no reason to recompute on every page load.
- If you batch-process births, retry failed ones in a separate pass rather than blocking the whole batch.
- For user-facing flows, show a soft "we're recalculating, please wait" state rather than a hard error. This recovers cleanly when our retry succeeds.
internal_errordate_out_of_supported_rangesun_calculation_failed