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.
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
email_not_verified	403	Confirm your email first. We've sent a confirmation link to your account's address; it expires in 24 hours.
ownership_denied	403	You do not have permission to access this resource.
session_required	403	This endpoint is for the signed-in dashboard; API keys can't use it. API keys call the calculation endpoints and GET /v1/keys/me.

Validation

Code	HTTP	Message
geocode_query_too_short	422	Search query must be at least 2 characters.
invalid_email	422	Please provide a valid email address.
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.
solar_day_out_of_range	422	The instant falls outside the solar day (sunrise to next sunrise), or the computed day/night span is invalid. Use an instant within that interval, or verify location and date.
sun_calculation_failed	422	Sunrise or sunset could not be computed for this date and location, usually because the Sun does not rise or set there that day (polar day or night). Verify latitude, longitude, and timezone, or use another date.
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.
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
account_action_limit_exceeded	429	This account action was asked for too often. Wait for the time in retry_after, then try again.
burst_limit_exceeded	429	Too many requests per minute. Please slow down.
ip_rate_limit_exceeded	429	Too many requests from this IP address. Please slow down.
login_attempts_exceeded	429	Too many failed sign-in attempts. Try again in 15 minutes, or reset your password.
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	You have reached your plan's limit of active API keys. Revoke a key or upgrade to add more.
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.