When you submit a name server change via the API (PUT /v1/dns/{domain_name}/name servers) or through the edit-name servers-tool MCP tool, the request may be rejected if the domain's current state or registry policies do not allow the change.
This article explains the most common rejection reasons and what to do about each. For the full endpoint reference, see DNS Record and Name Server Management: API Write Endpoints.
The domain is in a state that blocks changes (DOMAIN_STATE_PROHIBITS)
Name server changes are only permitted on active, unlocked domains in good standing. The change will be rejected if the domain is cancelled, deleted, or expired, or if it is currently transferring away to another registrar.
If the domain is in the process of transferring in, wait until the transfer completes before making name server changes.
What to do: Check the domain's current status using GET /v1/domains/{domain_name} or in your control panel. If the status is unexpected, contact 101domain support.
The domain has a registry update lock (BAD_REQUEST)
Two types of locks can prevent name server changes.
-
A
serverUpdateProhibitedlock is a registry-side lock that cannot be removed through the API. Contact 101domain support for assistance. -
A
clientUpdateProhibitedlock is client-managed. Disable it in your control panel before submitting the name server change via API.
You can check which registry statuses are currently applied to a domain using GET /v1/domains/{domain_name} and reviewing the registry_statuses field.
The domain has DNSSEC or Secure Web Accelerator active (BAD_REQUEST)
Domains with an active DNSSEC configuration or the Secure Web Accelerator (SWA) add-on require coordination before name server changes can be applied. Contact 101domain support to make name server changes on these domains.
A paid name server-change product is required (BAD_REQUEST)
Some TLDs require a paid name server change transaction. These cannot be completed through the API, the change must be initiated through the 101domain control panel.
Contact support if you are unsure whether your TLD has this requirement.
The name server hostnames were rejected by the registry (POLICY_VIOLATION, UNKNOWN_HOST_OBJECT, INVALID_INPUT)
Registries have their own requirements for name server hostnames. A name server hostname that does not exist as a registered host object at the registry returns UNKNOWN_HOST_OBJECT. Contact support for help.
Name servers that conflict with the registry's TLD policies return POLICY_VIOLATION.
Malformed hostnames or values the registry considers invalid return INVALID_INPUT.
The rate limit for this domain was exceeded (429 TOO_MANY_REQUESTS)
Name server changes are rate-limited on a per-domain basis. If you have submitted several name server changes for the same domain in a short period, subsequent requests will be rejected until the limit resets.
Check the x-ratelimit-limit and x-ratelimit-remaining response headers to see your current status. See API Key Limits for more on rate limiting.
Validation errors on the request itself (422 VALIDATION_ERROR)
Your request may be rejected before it reaches the registry if the payload is invalid. Check for fewer than 2 name servers (minimum is 2), more than 13 name servers (maximum is 13), duplicate name server hostnames including case-insensitive variants (e.g. ns1.example.com and NS1.EXAMPLE.COM), name server values that are not valid fully qualified hostnames, or the name servers field missing from the request body entirely.