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 | Monthly call allowance used up | Stop the reading, tell the user when it refreshes (error.data.resetAt), do not sleep-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 | The call's arguments carried no birth data. The server is stateless, so an earlier set_birth_profile does not supply it | Add the five birth fields to this call and 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.
A failed call does not lower the floor
Every reading carries a minimum tool-call count, 20 for a life-area question, 12 for a focused one, 5 for a lookup. Failures do not count toward it. If three calls error out inside a full reading, the reading still owes 20 successful ones before it may answer. Note the failure, keep going, and say in the synthesis which layer is missing. See reading depth and call floors.