GET STARTED

Errors

StarsAPI returns standard HTTP status codes plus a structured JSON error body with a machine-readable code, human-readable error message, and HTTP status. Build your error handling around the code field — error message strings may change over time.

Error shape

{
  "success": false,
  "error": "API key is required. Pass via X-Api-Key header or api_key parameter.",
  "code": "AUTH_MISSING_KEY",
  "status": 401
}

Error codes

HTTP	Code	Meaning
400	`BAD_REQUEST`	Generic malformed request (missing required field, wrong type)
400	`INVALID_PARAM`	A specific parameter failed validation (e.g. invalid sign name)
401	`AUTH_MISSING_KEY`	No API key provided in header, query, or body
401	`AUTH_INVALID_KEY`	API key format invalid or key has been revoked
403	`AUTH_FORBIDDEN`	Key valid but doesn't have permission for this endpoint
404	`NOT_FOUND`	Endpoint or resource not found
429	`RATE_LIMIT`	Per-minute, daily, monthly, or yearly limit exceeded
500	`SERVER_ERROR`	Internal error — retry with exponential backoff
503	`SERVICE_UNAVAILABLE`	Backend temporarily down (Swiss Ephemeris, AI provider, etc.)

Retries

Apply exponential backoff for these error codes:

429 RATE_LIMIT — check the Retry-After response header and wait that many seconds
500 SERVER_ERROR — retry up to 3 times with exponential backoff (1s, 2s, 4s)
503 SERVICE_UNAVAILABLE — retry up to 3 times with exponential backoff

Do not retry these:

All 4xx codes except 429 (client errors are not transient)