Diagnose backup and restore failures
Backup stays pending or running
Creation/trigger acknowledgement means work was queued. Inspect the backup detail and schedule status with bounded polling. Confirm the database is active; scheduled jobs skip paused databases and can skip disabled schedules. If it remains stuck, provide the backup/schedule/database IDs and UTC time to support. Repeated triggers can create additional work without fixing the problem.
Backup failed
Read error_message and verify the engine’s recovery requirements. MongoDB workers need mongodump/mongorestore and access to the private provisioning server. Redis workers need the internal provisioning connection; they do not need a whole-server RDB export. Existing .rdb artifacts cannot be restored through this endpoint; request a new logical backup after upgrading.
Schedule is rejected or runs at an unexpected time
All schedule times are UTC. Weekly requires day_of_week with Monday 0; monthly requires a day from 1–28. Retention is limited by the owner’s plan as well as the 1–365 field range. Read LIMIT_EXCEEDED or ENTITLEMENT_UNAVAILABLE instead of guessing a retention value.
Check next_run_at and the current active flag after updates. Multiple schedules share the database’s completed scheduled-backup retention history.
Restore failed or timed out
Use a completed, unexpired backup and an active target with the same engine, with membership in both workspaces. Confirm the explicit target UUID; an omitted target selects the source. Restore replaces target data within the selected database/namespace. PostgreSQL connections are interrupted.
A 202 response means the restore was queued. Poll the restore job, not just the backup artifact. A network timeout does not prove rollback or job cancellation. Inspect the existing job and target before repeating a restore. A failed attempt may have partially modified the target. Validate application data and permissions after the job reports completed. If a worker was forcibly terminated and the job remains running, an operator must confirm it has stopped before releasing the job or starting another attempt.