Integration Guide — Error Handling

No panics. No silent failures.

Every public Vedākṣha function returns Result<T, ComputeError>. The library does not panic, does not silently degrade, and does not return sentinel values like 0.0 or None to indicate an error condition. If something is wrong, you get an error.

The MCP layer wraps ComputeError into a structured JSON object with machine-readable error_code and a suggested_action that AI agents can read and act on autonomously.

The ComputeError Enum

ComputeError::DateOutOfRange{ julian_day: f64, valid_min: f64, valid_max: f64 }

The requested Julian Day falls outside the coverage window of the loaded ephemeris. DE440s covers 1550–2650 CE (JD 2287184.5–2816787.5). DE441 covers approximately 13000 BCE to 17000 CE.

Recovery:

Clamp the Julian Day to the valid range, or switch to DE441 for historical and far-future dates.

ComputeError::BodyNotAvailable{ body: Planet }

The requested planet or asteroid is not present in the loaded ephemeris file. The embedded DE440s covers the Sun, Moon, and 8 planets. Asteroids and Chiron require DE440 or a supplementary file.

Recovery:

Remove the body from the config, or load an ephemeris file that covers it.

ComputeError::InvalidFormat{ field: String, value: String, expected: String }

A parameter value did not match its expected type, range, or enum. This includes out-of-range latitudes, unrecognised house system names, and malformed Julian Days.

Recovery:

Inspect the field, value, and expected fields to correct the input.

ComputeError::IoError{ path: PathBuf, source: io::Error }

An ephemeris file could not be read — permission denied, file not found, or truncated data. Only raised when a file-based ephemeris is configured.

Recovery:

Verify the file path, permissions, and integrity of the ephemeris file.

Handling Errors in Rust

errors.rs

use vedaksha::prelude::*;
use vedaksha::ComputeError;

fn process_birth(jd: f64, lat: f64, lon: f64)
    -> Result<ChartGraph, ComputeError>
{
    match compute_chart(jd, lat, lon, &ChartConfig::vedic()) {
        Ok(graph) => Ok(graph),

        Err(ComputeError::DateOutOfRange { valid_min, valid_max, .. }) => {
            // Clamp to DE440s window and retry
            let clamped = jd.clamp(valid_min, valid_max);
            compute_chart(clamped, lat, lon, &ChartConfig::vedic())
        },

        Err(ComputeError::BodyNotAvailable { body }) => {
            // Retry without the unavailable body
            let config = ChartConfig::vedic()
                .without_body(body);
            compute_chart(jd, lat, lon, &config)
        },

        Err(e) => Err(e), // propagate other errors
    }
}

Handling Errors in Python

errors.py

import vedaksha as vk

try:
    chart = vk.compute_chart(1000000.0, 28.6, 77.2)

except vk.DateOutOfRange as e:
    print(f"JD {e.julian_day} out of range.")
    print(f"Valid: {e.valid_min:.1f} – {e.valid_max:.1f}")
    # e.suggested_action → human-readable recovery hint

except vk.BodyNotAvailable as e:
    print(f"Body {e.body} not in loaded ephemeris.")
    print(f"Suggested: {e.suggested_action}")

except vk.InvalidFormat as e:
    print(f"Bad value for '{e.field}': {e.value!r}")
    print(f"Expected: {e.expected}")

except vk.ComputeError as e:
    # Catch-all for any other ComputeError subclass
    print(f"Compute failed: {e}")
    print(f"Code: {e.error_code}")
    print(f"Suggested action: {e.suggested_action}")

Polar Fallback Warning

For latitudes above approximately 66°N or below 66°S, some house systems (notably Placidus and Koch) produce undefined cusps. Vedākṣha does not error — it automatically falls back to Whole Sign houses and attaches a PolarFallback warning to the result.

polar.rs

let graph = compute_chart(jd, 70.0, 25.0, &config)?;

if let Some(Warning::PolarFallback { original, fallback }) = &graph.warning {
    println!("Polar latitude:  →  fell back to ",
             graph.latitude, original, fallback);
    // House cusps in graph.houses are Whole Sign, not Placidus
}

MCP Error Codes

Every MCP error includes error_code,message, andsuggested_action in the JSON-RPC error.data object. AI agents can parse suggested_action and retry the correct call without human intervention.

error_codeHTTP statusMeaning

DATE_OUT_OF_RANGE422Julian Day outside coverage.

BODY_NOT_AVAILABLE422Planet not in ephemeris.

INVALID_FORMAT400Parameter type or value error.

CHART_NOT_FOUND404chart_id not found in session.

EPHEMERIS_NOT_LOADED503Function requires ephemeris data not yet loaded.

INTERNAL_ERROR500Unexpected internal failure. File a bug.

Design Philosophy

Vedākṣha is designed for use in automated pipelines — data import jobs, AI agents, batch processes — where there is no human to observe a wrong result. The library therefore refuses to guess. If it cannot compute a correct answer, it returns an error.

The suggested_action field exists specifically for AI agents. An agent that receives an error can read the action, correct its parameters, and retry — without escalating to the user. This loop has been tested with Claude and other MCP-compatible agents.

← Batch Computation·Data Sources →