Errors

All error responses follow a consistent format with machine-readable codes and human-readable messages.

Error response format

{
  "errors": [{
    "code": "invalid_parameter",
    "message": "Parameter 'system' has invalid value 'houses'. Valid systems: placidus, koch, ...",
    "param": "system",
    "suggestion": "Use 'placidus' (the default) or see docs for all 22 systems."
  }],
  "meta": {
    "request_id": "a1b2c3d4-..."
  }
}

code — Machine-readable error identifier (use this for programmatic handling)
message — Human-readable explanation of what went wrong
param — The parameter that caused the error (for validation errors only)
suggestion — A concrete next step to fix the problem

Error codes

400 Bad Request

Code	Cause	Recovery
`invalid_parameter`	Malformed or out-of-range value	Fix the parameter value
`missing_parameter`	Required parameter not provided	Add the missing parameter
`invalid_datetime`	Unparseable datetime or Julian Day	Use ISO 8601 UTC format or a valid Julian Day number
`conflicting_parameters`	Both `datetime` and `jd` provided	Provide only one time input

401 Unauthorized

Code	Cause	Recovery
`invalid_api_key`	Missing, malformed, or revoked key	Check your key at the dashboard

402 Payment Required

Code	Cause	Recovery
`insufficient_credits`	Free credits exhausted and no paid balance	Purchase credits

403 Forbidden

Code	Cause	Recovery
`origin_not_allowed`	Request origin not in key's allowed list	Update origin restrictions in dashboard

404 Not Found

Code	Cause	Recovery
`body_not_found`	Unrecognized celestial body name	See available bodies
`star_not_found`	Unrecognized star name	Use common name (e.g., "Aldebaran") or Bayer designation (e.g., "alTau")
`unknown_house_system`	Unrecognized house system	See house systems
`unknown_ayanamsha`	Unrecognized ayanamsha system	See ayanamshas

429 Too Many Requests

Code	Cause	Recovery
`rate_limit_exceeded`	Per-minute rate limit exceeded	Wait for `Retry-After` seconds

500 Internal Server Error

Code	Cause	Recovery
`computation_error`	Internal calculation failure	Retry; if persistent, contact support

503 Service Unavailable

Code	Cause	Recovery
`data_unavailable`	Ephemeris data files could not be loaded	Retry after a few seconds

Errors

On this page