Diagnose and handle Recall.ai bot failure states using status sub_codes (waiting room, denied consent, meeting not started)

Documented steps

1. Subscribe to bot status webhooks and/or GET https://<region>.recall.ai/api/v1/bot/{id}/, tracking status_changes across codes joining_call, in_waiting_room, in_call_not_recording, recording_permission_allowed, recording_permission_denied, in_call_recording, call_ended, done and fatal. Ref: https://docs.recall.ai/docs/bot-status-change-events
2. Treat 'fatal' as terminal and always read its sub_code - documented values include meeting_not_found, meeting_requires_sign_in, meeting_link_expired, meeting_link_invalid, meeting_password_incorrect, meeting_locked, meeting_full and meeting_ended. Ref: https://docs.recall.ai/docs/sub-codes
3. call_ended with sub_code meeting_not_started means the host never started the meeting - this is retryable with a later join_at rather than a hard failure.
4. Waiting-room stalls surface as in_waiting_room followed by call_ended with timeout_exceeded_waiting_room (Recall's own automatic_leave.waiting_room_timeout), a platform waiting-room timeout, or bot_kicked_from_waiting_room if the host rejected the bot.
5. Denied recording consent surfaces as recording_permission_denied, and on Zoom as the configuration sub_codes zoom_local_recording_disabled / zoom_local_recording_request_disabled / zoom_local_recording_request_disabled_by_host. Ref: https://docs.recall.ai/docs/common-zoom-recording-errors
6. Joined-but-useless bots end with sub_codes such as timeout_exceeded_noone_joined, timeout_exceeded_everyone_left, timeout_exceeded_in_call_not_recording, timeout_exceeded_silence_detected and the only-bots-detected variants, all governed by automatic_leave thresholds. Ref: https://docs.recall.ai/docs/automatic-leaving-behavior
7. Drive retries off the sub_code, not the status: retry meeting_not_started and waiting-room timeouts; do not retry meeting_not_found, meeting_link_invalid or meeting_password_incorrect without new meeting details from the user.
8. Tune automatic_leave at bot creation (waiting_room_timeout, noone_joined_timeout, in_call_not_recording_timeout, recording_permission_denied_timeout) - the defaults are long and will hide failures for many minutes.
9. Alert on your own budget if status_changes has not progressed past joining_call / in_waiting_room within the time you expect, rather than waiting for Recall's default timeouts.
10. Debug individual bots in the dashboard's bot explorer view (status history, screenshots, logs). Ref: https://docs.recall.ai/docs/debugging-bots
11. At the transport layer, treat 429 (honor Retry-After), 502/503/504 and 507 (no ad-hoc capacity, retry ~30s) as retryable, and 401/402/403 as auth/billing problems retries will not fix. Ref: https://docs.recall.ai/reference/errors