Errors
infra_db_unavailable
503 — Matter's primary database is temporarily unreachable; retry with backoff.
Last updated
Cause
Matter's primary data plane is a partitioned relational database. infra_db_unavailable fires when the platform cannot reach a partition that the request needs — connection pool exhausted, partition in failover, planned maintenance window in progress. The platform internally retries with short backoff before surfacing this error; receiving it means the retry budget has been spent.
This signal is platform-wide and short-lived. Failovers complete within seconds; pool saturation typically drains within tens of seconds; planned maintenance windows are announced via the status page. Persistent receipt of this code corresponds to an active incident.
Fix
- Retry the operation idempotently using the same
Idempotency-Key. Use exponential backoff with jitter. - Check the status page at
/runbooks/status-page-incidentsfor an active incident on the data plane. - If the workload is time-sensitive, surface the unavailability to the caller. Matter will not skip the operation; the database will be reachable again shortly.
- If the failure rate is sustained beyond what the status page reflects, contact support and quote the
request_id.
Related codes
infra_internal_error— an unexpected error, not specifically the database.infra_kms_unavailable— the key-management service is the affected dependency.op_service_degraded— deliberate load-shedding rather than a backend outage.