Get started

Error codes

All error responses share the same shape — a code, message, and request_id you can pass to support for debugging.

Error response shape

{
  "error": "Insufficient credits for this operation",
  "code": "insufficient_credits",
  "request_id": "req_a1b2c3d4"
}

400 Bad Request

Body or query parameters failed validation (missing field, wrong type, malformed date).

→ Check the response body for the failing field path. Compare against the schema in the API reference.

401 Unauthorized

No Authorization header, malformed bearer token, or unknown API key.

→ Verify the header is exactly "Authorization: Bearer <key>" — no extra whitespace.

403 Forbidden

API key is valid but the current tier does not include this endpoint.

→ Upgrade your tier in the dashboard, or call a lower-tier alternative if available.

404 Not Found

Endpoint path does not exist (typo) or the requested resource is missing.

→ Recheck the path against the API reference — common typos: trailing slash, wrong version prefix.

422 Unprocessable Entity

Request was syntactically valid but semantically rejected (e.g. birth_date in the future).

→ Read the response body for the specific business rule that failed.

429 Too Many Requests

Exceeded RPM or RPD limit for the current tier.

→ Honor the Retry-After header — back off exponentially or upgrade the tier.

500 Internal Server Error

Unexpected server-side fault — astrom8 incident or unhandled edge case.

→ Retry once after a short delay. If it persists, send the request_id to ops@astrom8.com.

502 Bad Gateway

LLM upstream returned an unparseable result (tarot/celtic-cross interpret stage).

→ No credit charged. Retry — managed LLM failover activates automatically after a short circuit window.

503 Service Unavailable

A required dependency is unavailable (e.g. no LLM key configured for tarot reports).

→ Wait and retry; check the status page if outage is widespread.

code	HTTP	Meaning
invalid_input	400	Body or query failed Zod schema validation. Response includes the failing field path.
unauthorized	401	Missing or invalid bearer token.
forbidden_tier	403	The API key tier does not include this endpoint.
insufficient_credits	402	Monthly quota exhausted and overage protection is enabled.
rate_limited	429	Per-tier RPM/RPD exceeded. Retry-After is provided.
pdf_unavailable	503	PDF rendering subsystem is offline. Returned by /api/v3/reports/thai-calendar/pdf.
interpretation_unavailable	503	All configured LLM inference routes failed or inference is not configured. No credit charged.
circuit_open	503	Circuit breaker tripped after consecutive upstream failures — auto-recovers within minutes.
image_generation_failed	503	Wheel image / natal image generation upstream failed. No credit charged.