Guide
Recover from errors
Most failures inside a reading are transient. The right recovery preserves the seven-phase chain instead of restarting it.
What can fail
| Code | Cause | Recovery |
|---|---|---|
| 429 | Daily limit reached | Stop reading, surface to user, do not retry |
| 502 / 503 / 504 | Engine transient | Exponential backoff, max 2 retries |
| 400 INVALID_EVENT_NAME | Unknown event keyword | Map to nearest event or use house_group override |
| 400 BIRTH_DATA_MISSING | No birth profile in context | Call set_birth_profile, retry once |
| 401 | Bad or expired token | Refresh OAuth or rotate API key, do not retry blindly |
Idempotency
All Lumin tool calls are safe to retry. They are pure computations with no side effects, so retrying after a transient failure produces the same result. The metering also does not double-count: failed calls do not consume budget.
Partial readings
If a single phase fails (say, the transit hierarchy), the chart foundation phase is still valid, so you do not need to restart. Either skip the failed phase with a note in the synthesis, or retry that phase only. Lumin's tools are independently scoped, so this works cleanly.