Error Reference

Every error response from the Asterwise API follows a structured format. Use the error code to handle specific cases in your application.

Error Envelope

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human readable",
  "details": {}
}

Quick Reference

Error Code	HTTP Status	Description
AUTHENTICATION_FAILED	401	General authentication failure — credentials rejected or auth flow could not be completed.
MAGIC_LINK_NOT_FOUND	401	Magic link token was not found or is no longer valid.
MAGIC_LINK_ALREADY_USED	401	Magic link has already been redeemed once.
MAGIC_LINK_EXPIRED	401	Magic link token expired before verification.
SESSION_NOT_FOUND	401	Session token does not map to an active session.
SESSION_REVOKED	401	Session was explicitly revoked.
SESSION_EXPIRED	401	Session duration elapsed.
EXCHANGE_CODE_NOT_FOUND	401	Exchange code is missing, invalid, or expired.
EXCHANGE_CODE_ALREADY_USED	401	Exchange code was already redeemed once.
API_KEY_NOT_FOUND	401	API key was not found.
API_KEY_REVOKED	401	API key is inactive/revoked.
API_KEY_INVALID	401	API key format is malformed.
ACCOUNT_NOT_FOUND	404	Requested account does not exist.
KEY_NOT_FOUND	404	API key does not exist or caller lacks ownership.
ENDPOINT_RESTRICTED	403	API key is not permitted for endpoint.
IP_RESTRICTED	403	Requesting IP is blocked for this key.
MAGIC_LINK_IP_LIMIT_EXCEEDED	429	Too many magic-link requests from same IP in time window.
MAGIC_LINK_EMAIL_LIMIT_EXCEEDED	429	Too many magic-link requests for one email in time window.
EXCHANGE_CODE_ATTEMPT_LIMIT_EXCEEDED	429	Too many failed exchange attempts from same source.
MONTHLY_USAGE_LIMIT_EXCEEDED	429	Plan monthly call allowance reached.
BURST_LIMIT_EXCEEDED	429	Per-minute burst threshold exceeded.
INVALID_EMAIL	422	Email input failed validation.
INVALID_KEY_NAME	422	API key name length/format invalid.
INVALID_REQUEST_BODY	422 / 400	Request JSON/body is missing or malformed.
DATE_OUT_OF_SUPPORTED_RANGE	422	Date is outside supported engine range.
PLAN_NOT_FOUND	422	Requested plan identifier is invalid.
MAX_KEYS_EXCEEDED	409	Account hit max allowed active keys.
SUBSCRIPTION_NOT_FOUND	404	No active subscription found where one was expected.
INSUFFICIENT_TIER	402	Endpoint requires higher plan tier than current key.
PAYMENT_VERIFICATION_FAILED	400	Payment signature verification failed.
ORDER_CREATION_FAILED	400	Billing order could not be created.
ALREADY_ON_PLAN	400	Requested upgrade/downgrade targets current active plan.
PAYMENT_PROVIDER_UNAVAILABLE	503	Payment provider temporarily unavailable.
PAYMENT_REQUEST_INVALID	400	Payment provider rejected the request as invalid.
GEOCODE_QUERY_TOO_SHORT	422	Geocode query is shorter than minimum length.
CITY_NOT_FOUND	404	No geocoding match found for location input.
GEOCODE_UNAVAILABLE	503	Geocoding dependency temporarily unavailable.
EMAIL_DELIVERY_FAILED	503	Email provider could not deliver transactional mail.
INTERNAL_ERROR	500	Unexpected internal failure.

Detailed Categories

Authentication Errors

AUTHENTICATION_FAILED401

General authentication failure — credentials rejected or auth flow could not be completed.

Common causes

Invalid email/password combination
Google OAuth token rejected
Auth provider returned error

How to fix: Verify credentials are correct and retry. For Google auth, ensure the ID token is fresh.

MAGIC_LINK_NOT_FOUND401

Magic link token was not found or is no longer valid.

Common causes

Wrong token in request
Token already expired
Token typo/copy issue

How to fix: Request a fresh magic link and use the latest token.

MAGIC_LINK_ALREADY_USED401

Magic link has already been redeemed once.

Common causes

Reusing the same link
Duplicate browser/tab submission
Replay attempt

How to fix: Request a new magic link and complete login once.

MAGIC_LINK_EXPIRED401

Magic link token expired before verification.

Common causes

User waited too long
Delayed email open
Stale inbox link

How to fix: Request and use a new magic link immediately.

SESSION_NOT_FOUND401

Session token does not map to an active session.

Common causes

Invalid/missing session token
Wrong environment token
Token already removed

How to fix: Sign in again and use the new session token.

SESSION_REVOKED401

Session was explicitly revoked.

Common causes

Logout from current/all devices
Security invalidation
Account action revoked sessions

How to fix: Sign in again to create a new active session.

SESSION_EXPIRED401

Session duration elapsed.

Common causes

Long inactivity
Old stored token
Expired browser/app session

How to fix: Re-authenticate and refresh stored session token.

EXCHANGE_CODE_NOT_FOUND401

Exchange code is missing, invalid, or expired.

Common causes

Wrong code pasted
Code already consumed
Code TTL exceeded

How to fix: Restart auth flow to generate a fresh exchange code.

EXCHANGE_CODE_ALREADY_USED401

Exchange code was already redeemed once.

Common causes

Reusing same code
Retry after successful exchange
Concurrent redemption

How to fix: Request a new code via login flow.

API_KEY_NOT_FOUND401

API key was not found.

Common causes

Invalid key string
Deleted key
Wrong project/environment key

How to fix: Create/regenerate an API key and retry.

API_KEY_REVOKED401

API key is inactive/revoked.

Common causes

Key manually deactivated
Key rotated
Account cleanup/revocation

How to fix: Use an active key or rotate/create a new one.

API_KEY_INVALID401

API key format is malformed.

Common causes

Missing Bearer prefix
Truncated key
Extra whitespace/invalid characters

How to fix: Send header as Authorization: Bearer YOUR_KEY.

ACCOUNT_NOT_FOUND404

Requested account does not exist.

Common causes

Stale account reference
Deleted account
Invalid account context

How to fix: Re-authenticate and verify account exists.

KEY_NOT_FOUND404

API key does not exist or caller lacks ownership.

Common causes

Wrong key ID
Key deleted
Cross-account access attempt

How to fix: Use a valid owned key ID and authenticated owner context.

ENDPOINT_RESTRICTED403

API key is not permitted for endpoint.

Common causes

Restricted endpoint by key policy
Legacy endpoint disabled
Policy mismatch

How to fix: Use allowed endpoint/key policy or upgrade integration path.

IP_RESTRICTED403

Requesting IP is blocked for this key.

Common causes

IP allowlist mismatch
Proxy/NAT IP changed
Corporate egress changed

How to fix: Update allowlist/policy and retry from approved IP.

Rate Limit Errors

MAGIC_LINK_IP_LIMIT_EXCEEDED429

Too many magic-link requests from same IP in time window.

Common causes

Rapid retries
Scripted abuse
Shared office NAT burst traffic

How to fix: Wait for retry window and reduce request frequency.

MAGIC_LINK_EMAIL_LIMIT_EXCEEDED429

Too many magic-link requests for one email in time window.

Common causes

Repeated clicks
Automated retries
User confusion/re-submission loops

How to fix: Wait and retry once; avoid repeated submit actions.

EXCHANGE_CODE_ATTEMPT_LIMIT_EXCEEDED429

Too many failed exchange attempts from same source.

Common causes

Wrong code brute-force
Stale code retries
Script loop failures

How to fix: Pause attempts and restart authentication flow.

MONTHLY_USAGE_LIMIT_EXCEEDED429

Plan monthly call allowance reached.

Common causes

Volume exceeded plan
Traffic spike
No throttling/caching client side

How to fix: Upgrade plan or reduce/queue request volume.

BURST_LIMIT_EXCEEDED429

Per-minute burst threshold exceeded.

Common causes

Request burst from workers
Retry storm
Missing client backoff

How to fix: Add rate limiting, jittered retries, and queueing.

Validation Errors

INVALID_EMAIL422

Email input failed validation.

Common causes

Missing @
Invalid format
Empty value

How to fix: Submit a valid, permanent email address.

INVALID_KEY_NAME422

API key name length/format invalid.

Common causes

Empty name
Too long name
Malformed payload

How to fix: Use key name within allowed length and valid body JSON.

INVALID_REQUEST_BODY422 / 400

Request JSON/body is missing or malformed.

Common causes

Invalid JSON
Wrong content type
Missing required fields

How to fix: Send valid JSON with required schema fields.

DATE_OUT_OF_SUPPORTED_RANGE422

Date is outside supported engine range.

Common causes

Date too old/new
Bad date parse fallback
Wrong timezone/date conversion

How to fix: Use supported birth date range accepted by API validators.

PLAN_NOT_FOUND422

Requested plan identifier is invalid.

Common causes

Wrong SKU/plan string
Stale frontend enum
Typo in payload

How to fix: Use valid plan/SKU values from current docs.

MAX_KEYS_EXCEEDED409

Account hit max allowed active keys.

Common causes

Too many active keys
No cleanup of old keys
Repeated key creation

How to fix: Revoke old keys or rotate existing instead of creating new ones.

SUBSCRIPTION_NOT_FOUND404

No active subscription found where one was expected.

Common causes

Subscription expired/cancelled
Account mismatch
Not yet activated

How to fix: Activate/renew plan and verify account context.

INSUFFICIENT_TIER402

Endpoint requires higher plan tier than current key.

Common causes

Calling restricted route with lower tier
Stale plan entitlement
Incorrect key

How to fix: Upgrade plan or use key with required tier.

Billing Errors

PAYMENT_VERIFICATION_FAILED400

Payment signature verification failed.

Common causes

Tampered signature
Wrong webhook secret
Order/payment ID mismatch

How to fix: Recompute signature with correct secret and retry verification.

ORDER_CREATION_FAILED400

Billing order could not be created.

Common causes

Invalid billing payload
Provider-side validation failure
Transient provider issue

How to fix: Validate request fields and retry with new idempotency key.

ALREADY_ON_PLAN400

Requested upgrade/downgrade targets current active plan.

Common causes

Re-selecting same SKU
Duplicate plan change action
Stale UI state

How to fix: Choose different target plan or skip plan-change call.

PAYMENT_PROVIDER_UNAVAILABLE503

Payment provider (Razorpay) is temporarily unavailable.

Common causes

Razorpay outage
Network timeout reaching payment provider
Circuit breaker open

How to fix: Retry after a short delay. Check status.razorpay.com for provider status.

PAYMENT_REQUEST_INVALID400

Payment provider rejected the request as invalid.

Common causes

Malformed payment payload
Unsupported currency or amount
Provider-side validation failure

How to fix: Verify payment fields and amounts match provider requirements, then retry.

Calculation Errors

GEOCODE_QUERY_TOO_SHORT422

Geocode query is shorter than minimum length.

Common causes

One-character search
Empty query after trim
Missing query param

How to fix: Send query with at least 2 characters.

CITY_NOT_FOUND404

No geocoding match found for location input.

Common causes

Misspelled city
Very ambiguous input
Unsupported locality format

How to fix: Provide clearer city/state/country string.

GEOCODE_UNAVAILABLE503

Geocoding dependency temporarily unavailable.

Common causes

Upstream outage
Timeout/network issue
Circuit-breaker open

How to fix: Retry with backoff or use direct coordinates/timezone.

Server Errors

EMAIL_DELIVERY_FAILED503

Email provider could not deliver transactional mail.

Common causes

Provider outage
Circuit breaker open
Template/send API failure

How to fix: Retry later and monitor email provider status.

INTERNAL_ERROR500

Unexpected internal failure.

Common causes

Unhandled exception
Dependency failure
Transient infrastructure issue

How to fix: Retry once; if persistent, contact support with request ID.