This article covers the most common reasons a DNS record create, edit, or delete request might fail when using the API or MCP tools, and how to resolve each. For the full endpoint reference, see DNS Record and Name Server Management: API Write Endpoints.
The domain is not using 101domain managed nameservers (NAMESERVERS_NOT_LOCAL)
The DNS write endpoints — and the corresponding MCP tools — can only manage records for domains that are currently using 101domain managed nameservers or Secure Web Accelerator (SWA) nameservers provided by 101domain. If your domain is delegated to external nameservers, the API cannot read or modify the DNS zone.
What to do: Either manage the records directly with your external DNS provider, or update the domain's nameservers to 101domain nameservers first using PUT /v1/dns/{domain_name}/nameservers or edit-nameservers-tool.
See also: Why Does the DNS Records Endpoint Return an Empty Array or Error?
One or more record IDs were not found (404 NOT_FOUND)
The PATCH and DELETE endpoints are atomic. If any id in your batch is not found, the entire request is rejected and no records are changed. The response includes an errors.not_found_ids array listing the IDs that could not be matched.
Common causes: the record was already deleted, the record was recently edited and its id changed, or the ID was copied from a different domain's record list.
What to do: Re-fetch the current record list with GET /v1/dns/{domain_name}/records to confirm current IDs, then retry.
Note: when using the MCP tools, you do not need to manage record IDs yourself — the tools handle this for you.
A record's ID changed after an edit
A record's id is derived from its content. When any field of a record is changed. Its TTL, value, priority, or any other field — the record receives a new id. The old id is no longer valid and will return a 404 NOT_FOUND error if used in a subsequent PATCH or DELETE request.
What to do: After editing a record, use the new id returned in the PATCH response. If you are running a sequence of operations, re-fetch the record list with GET /v1/dns/{domain_name}/records to get current IDs before each write operation.
A required field is missing or doesn't apply to the record type (422 VALIDATION_ERROR)
Each record type has specific required fields. Submitting an MX record without priority and target, or including a priority field on an A record, will result in a validation error. Additionally, name and type are immutable — including either in a PATCH request body will be rejected. To change a record's name or type, delete the existing record and create a new one.
What to do: Review the field requirements for each record type in DNS Record and Name Server Management: API Write Endpoints and resubmit with the correct fields.
The batch exceeds 25 records (422 VALIDATION_ERROR)
POST, PATCH, and DELETE each accept a maximum of 25 records per request. Submitting more than 25 will return a 422 VALIDATION_ERROR.
Split your batch into multiple requests of 25 or fewer records each.
The record conflicts with an existing record in the zone (POLICY_VIOLATION)
DNS has rules about which record types can coexist at the same name. The most common conflict is a CNAME — a CNAME cannot exist at a hostname that already has other records (such as an A or MX record at the same name), and other records cannot be added at a name that already has a CNAME.
What to do: Check existing records at the target hostname using GET /v1/dns/{domain_name}/records?name=<hostname>. Remove or restructure conflicting records before adding the new one.
An attempt to create an apex NS record was rejected (INVALID_INPUT)
Apex NS records — the nameservers for the domain root itself — do not appear in the DNS record list returned by GET /v1/dns/{domain_name}/records and cannot be created or deleted through the DNS records endpoints. Attempts to create an NS record with name: @ will be rejected with INVALID_INPUT.
To change a domain's nameservers, use PUT /v1/dns/{domain_name}/nameservers or the edit-nameservers-tool MCP tool. Subdomain NS delegations (e.g. delegating sub.example.com to different nameservers) are fully supported via the DNS records endpoints.
The zone has reached its record limit (ZONE_RECORD_LIMIT_EXCEEDED)
DNS zones have a maximum number of records. If your zone has hit this limit, new records cannot be added until existing records are removed. Delete unused or outdated records to make room, or contact 101domain support if you believe you need a higher limit.