Error Codes

All API errors return a consistent JSON envelope:

{
  "success": false,
  "error": "Human-readable error message"
}

HTTP status codes

Status	Name	Description
`400`	Bad Request	Missing or invalid request parameters (e.g. missing `birthDate`)
`401`	Unauthorized	Missing or invalid API key in the `Authorization` header
`403`	Forbidden	Your subscription doesn't include the required product for this endpoint
`404`	Not Found	The requested endpoint doesn't exist
`429`	Too Many Requests	Rate limit or monthly quota exceeded
`500`	Internal Server Error	Unexpected server error — contact support if persistent
`502`	Bad Gateway	Upstream service error (e.g. AI provider timeout for SAGE queries)
`503`	Service Unavailable	A required service is temporarily down (e.g. knowledge database)

Common error examples

Missing required field

{
  "success": false,
  "error": "birthDate is required"
}

Invalid API key

{
  "success": false,
  "error": "Invalid API key"
}

Product not available

{
  "success": false,
  "error": "Product not available for your subscription"
}

Rate limit exceeded

{
  "success": false,
  "error": "Rate limit exceeded. Try again in 60 seconds."
}

Location not found

{
  "success": false,
  "error": "City 'XYZ' not found. Please provide a valid city name (e.g., \"London\", \"Manila\", \"New York\") or lat/lon coordinates."
}

ISO country code rejected

{
  "success": false,
  "error": "City 'BG' not found. \"BG\" looks like a country code. Try a city name instead: Sofia, Plovdiv, Varna."
}

Use the Validate Location endpoint to pre-check city names before making calculation requests.

Tips

Check the error field for a human-readable description of what went wrong
4xx errors indicate client-side issues — check your request parameters and API key
5xx errors are server-side — retry after a short delay, or contact support
Failed requests (4xx/5xx) are not counted against your monthly unit quota