Error reference

Every error response from the Asterwise API conforms to a stable 8-field envelope. This reference page lists every error code we may return, organized by category.

Each error page documents:

• What the error means in plain English
• When you'll see it
• A code example showing how to handle it in production
• How to avoid the error in the first place

All 401, 403, 404, 422, 429, and 5xx responses follow the same shape. OAuth endpoints (/v1/oauth/*) are the one exception — they return RFC 6749-compliant {error, error_description} per the OAuth standard.

Authentication

Code	HTTP	Message
api_key_invalid	401	Invalid API key format.
api_key_missing	401	API key is missing. Include it in the Authorization header as 'Bearer YOUR_KEY'.
api_key_not_found	401	The provided API key was not found. Verify the key in your Asterwise dashboard.
api_key_revoked	401	This API key has been revoked.
authentication_failed	401	We couldn't authenticate your request. Verify your credentials and try again.
exchange_code_already_used	401	Exchange code has already been used.
exchange_code_not_found	401	Exchange code not found or expired.
magic_link_already_used	401	This magic link has already been used.
magic_link_expired	401	This magic link has expired. Request a new one.
magic_link_not_found	401	Magic link not found or already expired.
session_expired	401	Your session has expired. Please sign in again.
session_not_found	401	Session not found. Please sign in again.
session_revoked	401	This session has been revoked. Please sign in again.

Authorization

Code	HTTP	Message
endpoint_restricted	403	This API key is not permitted to call this endpoint.
insufficient_tier	402	This endpoint requires a higher tier. Please upgrade your plan.
ownership_denied	403	You do not have permission to access this resource.

Validation

Code	HTTP	Message
date_out_of_supported_range	422	Date is outside the supported range. Supported range is 1800-01-01 to 2099-12-31.
geocode_query_too_short	422	Search query must be at least 2 characters.
invalid_email	422	Please provide a valid email address.
invalid_key_name	422	Key name must be between 1 and 50 characters.
invalid_request_body	422	Request body is missing or malformed.
location_required	422	A location is required for this calculation. Provide either a location name, or latitude, longitude, and timezone.
payload_too_large	413	Request body exceeds maximum allowed size of 64KB.
plan_not_found	422	The specified plan does not exist.
polar_latitude_unsupported	422	Calculations cannot be performed at this latitude. Locations within the polar circles may not have a computable sunrise, sunset, or houses on this date. Use a nearby non-polar location, or a different date.
sun_calculation_failed	422	Sunrise or sunset could not be computed for this date and location. Verify latitude, longitude, and timezone, or provide a specific birth time.
validation_error	422	The request couldn't be processed. See the 'details' field for specific field-level issues.

Not Found

Code	HTTP	Message
account_not_found	404	No account was found matching the provided credentials. Sign up at asterwise.com or verify your sign-in details.
city_not_found	404	No locations found matching your query.
interpretation_not_found	404	Interpretation not found for the given number or context.
key_not_found	404	API key not found or you do not have permission to access it.
resource_not_found	404	The requested resource was not found at this endpoint. Verify the URL path and resource identifier.
subscription_not_found	404	No active plan found.

Rate Limiting

Code	HTTP	Message
burst_limit_exceeded	429	Too many requests per minute. Please slow down.
exchange_code_attempt_limit_exceeded	429	Too many failed exchange attempts.
ip_rate_limit_exceeded	429	Too many requests from this IP address. Please slow down.
magic_link_email_limit_exceeded	429	Too many magic link requests for this email.
magic_link_ip_limit_exceeded	429	Too many magic link requests from this IP.
monthly_usage_limit_exceeded	429	Monthly API call limit reached. Upgrade your plan to continue.

Billing

Code	HTTP	Message
already_on_plan	400	You are already on this plan.
max_keys_exceeded	409	Maximum of 10 API keys per account reached.
order_creation_failed	400	Failed to create payment order. Please try again.
payment_provider_unavailable	503	Payment provider is temporarily unavailable. Please try again shortly.
payment_request_invalid	400	Payment provider rejected the request as invalid.
payment_verification_failed	400	Payment signature verification failed.
subscription_expired	402	Your subscription has expired. Please renew at asterwise.com/dashboard to continue.

Infrastructure

Code	HTTP	Message
email_delivery_failed	503	We are having trouble sending email right now. Please try again in a few minutes.
ephemeris_unavailable	503	Ephemeris calculations are temporarily unavailable. Please try again in a few minutes, or contact [email protected] if the problem persists.
geocode_unavailable	503	Location search is temporarily unavailable. Please try again shortly.
internal_error	500	Something went wrong on our end. Please try again, or contact [email protected] if the problem persists. Include your request_id when contacting support.