Ephemeris Unavailable

Reference · Errors

ephemeris_unavailable503

Infrastructure · Any calculation that reads the ephemeris

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 data files with precise planetary positions. This error means the server that took your request could not load those files. The request was structurally valid; the server just had no ephemeris data to compute the answer from.

When you'll see this

• A core ephemeris file is missing on that server: sepl_18.se1 (planets) or semo_18.se1 (Moon). Together they cover 1800 to 2399, so every birth date the API accepts (1800-01-01 to 2099-12-31) needs them. This is a deploy or configuration problem on our side.
• Filesystem permissions stop the API process from reading those files (also on our side).

It never depends on your input: a date outside the supported range is rejected earlier with validation_error, and an error inside a Swiss Ephemeris calculation returns internal_error.

Learn more about how this works

Think of the ephemeris as the dataset every astrology calculation reads from. It is not optional and cannot be synthesized from other inputs, so when it is missing no answer is possible. The good news: it usually recovers on retry, because a fault like this normally affects one server while the others keep working. Keep the retry budget short; if the files are missing everywhere, 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"
}

NEW TO APIS?

Quick fix

1. Wait 30-60 seconds and retry the request.
2. If it keeps failing, email [email protected] with the original request_id.
3. Check status.asterwise.com — if there's an active ephemeris incident, we'll have posted it.

PRODUCTION ENGINEER

Recovery pattern

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

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")

TypeScript

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.