Fail a name over with a health check

Attach an uptime check to an A, AAAA or CNAME record set, so the name answers failover values while its target is down.

Last updated 18 November 2026View as Markdown

Replace zone-id with the id of your hosted zone, and check-id with the id of an uptime check that watches the primary target.

How it behaves

  • While the uptime check is down, the nameservers answer the set's failover values; when it is up again, the set's own values. A paused check, or one in any other state, is not down.
  • With no failover values, the set's own values are answered whatever the check says.
  • A health-checked set is served with a TTL of at most 60 seconds, so resolvers see the switch soon. The stored TTL is not changed.
  • Health checks go on A, AAAA and CNAME sets only. A routed set takes a check per variant instead (see Route by weight or location), and an ALIAS follows its target.
  • Deleting the uptime check removes it from the set; the set's own values are then always answered.

Prerequisites

  • An uptime check for the primary target, created under Monitoring (monitoring:CreateCheck).
  • Permission for dns:ChangeRecords on the zone.
  • In the console, also dns:ListZones to open Hosted zones (without it the page shows an access-denied notice), dns:GetZone to open the zone (without it the zone's page is not found), and monitoring:DescribeChecks to choose a check. Without it, or without any check, the dialog says "Create an uptime check under Monitoring to fail this name over when its target goes down."

Attach the health check

  1. Open the zone. On the Records tab, choose Add record, or Edit record in the row's actions menu.
  2. Enter the Name, a Type of A, AAAA or CNAME, and the primary Values, one per line.
  3. Under Health check, choose the uptime check.
  4. For Failover values, one per line, enter the values to answer while the check is down.
  5. Choose Add (or Save).

The table shows the set's values, then "checked by check name; fails over to …".

To remove the check, choose None (always answer the values above) under Health check and save, or in the API send "healthCheckId": null with "failoverValues": [].

When the record is refused

All with 400:

  • "Only A, AAAA and CNAME records can have a health check".
  • "Uptime check not found" when the check is not one of your organization's.
  • "Failover values need a health check" when you send failover values without a check, including an edit that removes the check but keeps the stored failover values.
  • "Failover: 198.51.100.300 is not an IPv4 address" for a failover value in the wrong format.
  • "A CNAME has exactly one failover value".
  • "A routed set takes health checks per variant, not a failover health check".
Did this page help you?