Documentation / Guides

The safety model

Namecheap's API replaces a domain's entire record set on every write. There is no partial update, no server-side undo, and a malformed record is accepted as readily as a good one. Three separate mechanisms exist because of that, and they protect against different things.

1. Validation — before anything is sent

Every command that writes DNS checks its records first and refuses to write anything if any of them would be invalid. Checks run twice: on your input, then again on the zone the write would produce, so a conflict with a record already in the zone is caught as well.

$ namecheap dns add example.com A @ 1.2.3.400
✗ Invalid record
A @ 1.2.3.400 1800
  Problem: "1.2.3.400" is not a valid IPv4 address — each of the
           four parts must be a number from 0 to 255
  Fix:     Use an address such as 185.199.108.153. To point at
           a hostname instead, use CNAME (on a subdomain) or
           ALIAS (at the domain root).

Error: Validation error: 1 record(s) would be invalid — nothing was changed

Problems that are legal but probably unintended — a TXT value over the 255-character single-string limit, a duplicate record, an SRV host without a leading underscore — are reported as warnings and do not block the write.

Validation is scoped to the hosts you are changing. A pre-existing problem elsewhere in the zone never blocks an unrelated update, so you are not forced to fix someone else's mess before adding a record.

With --json, issues are emitted as an issues array rather than printed.

2. Snapshots — before the zone changes

Because there is no server-side undo, the zone as it stands is saved locally before each change, and dns rollback puts it back. A rollback goes through the same diff-and-confirm flow as any other write, so you see exactly what it will do first.

# what snapshots exist for a domain
namecheap dns rollback example.com --list

# undo the last change
namecheap dns rollback example.com

# go back to a specific snapshot (id from --list)
namecheap dns rollback example.com --at 1755600000

A rollback restores the zone exactly as it was, so records added since the snapshot are removed as well as changed ones put back. That is the point — a partial restore would leave you somewhere you have never been.

Snapshots carry the account's email routing mode alongside the records. Restoring records without it would silently unpublish your MX. Snapshots taken before an email-forwarding change also record the forwarded mailboxes; snapshots taken before an ordinary DNS write do not, because a setHosts call cannot change forwarding and restoring an empty set would delete mailboxes the change never touched.

The 20 most recent snapshots per domain are kept, under your platform's application-data directory — override with NAMECHEAP_BACKUP_DIR. Pass --no-backup to skip taking one. A snapshot that cannot be written is a warning, not a failure: it does not stop the change you asked for.

3. Read-back — after the write

A success response is not proof the change landed. After a write the zone is read again and compared against what was sent, and a mismatch is its own error rather than a green tick over a zone that never changed.

Error: Namecheap reported success but the following records are not
       present after the write:
  A @ 185.199.108.153 1800

Retries, and what is never retried

A request is abandoned after 30 seconds and a connection after 10 — without that, a dropped connection hangs forever and the retry policy never fires. Transient failures (a timeout, a dropped connection, an HTTP 5xx, a rate-limit response, or a gateway page where the XML should be) are retried up to three times with a growing wait of 2s, 4s then 8s. -v reports each retry as it happens.

Only commands that can be repeated safely are retried. Every write sends the complete desired state rather than a delta, so repeating one converges on the same zone. Everything that spends money is deliberately excluded — domains renew, whoisguard renew and transfer start — so a lost response can never become a second charge.

Confirmations, and skipping them

Anything destructive or billable shows what it will do and asks first. --dry-run shows the diff and stops; -y skips the prompt for unattended use. Reach for -y in CI, not at a keyboard.

None of this covers the case where Namecheap itself is wrong about its own state — the domain listing reports IsLocked="false" for domains that are in fact locked, which is why domains info reads the lock separately. For end-to-end assurance against a real account, the repository ships scripts/live-check.sh, which drives the built binary against a real domain and reads every change back.