Batch Change Errors

  1. By-Change Accumulated Errors
  2. Full-Request Errors

BY-CHANGE ACCUMULATED ERRORS

Since all of the batch changes are being validated simultaneously, it is possible to encounter a variety of errors for a given change. Each change that is associated with errors will have its own list of errors containing one or more errors; any changes without the errors list have been fully validated and are good to submit. If any change in the batch is deemed invalid for any reason, no changes in the batch will be applied. These types of errors will probably account for the majority of errors that users encounter.

By-change accumulated errors are errors that get collected at different validation stages and correspond to individual change inputs. By-change accumulated errors are grouped into the following stages:

  • Independent input validations: Validate invalid data input formats and values.
  • Record and zone discovery: Resolve record and zone from fully-qualified input name.
  • Dependent context validations: Check for sufficient user access and conflicts with existing records or other submissions within the batch.

Since by-change accumulated errors are collected at different stages, errors at later stages may exist but will not appear unless errors at earlier stages are addressed.

EXAMPLE ERROR RESPONSE BY CHANGE

[
   {
      "changeType": "Add",
      "inputName": "good-A.another.example.com.",
      "type": "A",
      "ttl": 200,
      "record": {
        "address": "1.2.3.4"
      }
   },
   {
      "changeType": "Add",
      "inputName": "duplicate.example.com",
      "type": "CNAME",
      "ttl": 200,
      "record": {
         "cname": "test.example.com."
      },
      "errors": [
         "Record with name "duplicate.example.com." is not unique in the batch change. CNAME record cannot use duplicate name."
      ]
   },
   {
      "changeType": "Add",
      "inputName": "duplicate.example.com",
      "type": "A",
      "ttl": 300,
      "record": {
         "address": "1.2.3.4"
      }
   },
   {
      "changeType": "Add",
      "inputName": "bad-ttl-and-invalid-name$.sample.com.”,
      "type": "A",
      "ttl": 29,
      "record": {
         "address": "1.2.3.4"
      },
      "errors": [
         "Failed validation 29, TTL must be between 30 and 2147483647.",
         "Failed validation bad-ttl-and-invalid-name$.sample.com., valid domain names are a series of one or more labels joined by dots and terminate on a dot."
      ]
   }
]

By-Change Errors

  1. Invalid Domain Name
  2. Invalid Length
  3. Invalid Record Type
  4. Invalid IPv4 Address
  5. Invalid IPv6 Address
  6. Invalid IP Address
  7. Invalid TTL
  8. Invalid Batch Record Type
  9. Zone Discovery Failed
  10. Record Already Exists
  11. Record Does Not Exist
  12. CNAME Conflict
  13. User Is Not Authorized
  14. Record Name Not Unique In Batch Change
  15. Invalid Record Type In Reverse Zone

1. Invalid Domain Name

Error Message:
Invalid domain name: "<input>", valid domain names must be letters, numbers, and hyphens, joined by dots, and terminate with a dot.
Details:

Fully qualified domain names, must be comprised of labels, separated by dots. A label is a combination of letters, digits, and hyphens. They must also be absolute, which means they end with a dot.

Syntax:

<domain> ::= <subdomain> | " "

<subdomain> ::= <label> | <subdomain> "." <label>

<label> ::= <letter> [ [ <ldh-str> ] <let-dig> ]

<ldh-str> ::= <let-dig-hyp> | <let-dig-hyp> <ldh-str>

<let-dig-hyp> ::= <let-dig> | "-"

<let-dig> ::= <letter> | <digit>

<letter> ::= any one of the 52 alphabetic characters A through Z in
upper case and a through z in lower case

<digit> ::= any one of the ten digits 0 through 9

More info can be found at:

RFC 1035, DOMAIN NAMES - IMPLEMENTATION AND SPECIFICATION, Section 2.3.1. Preferred name syntax

2. Invalid Length

Error Message:
Invalid length: "<input>", length needs to be between <minLengthInclusive> and <maxLengthInclusive> characters.
Details:

The length of the input did not fit in the range in [minLengthInclusive, maxLengthInclusive].

3. Invalid Record Type

Error Message:
Invalid record type: "<input>", valid record types include <valid record types>.
Details:

The record type input must match one of the valid record types. Not all DNS record types are currently supported.

4. Invalid IPv4 Address

Error Message:
Invalid IPv4 address: "<input>"
Details:

The IPv4 address input is not a valid IPv4 address. Accepted inputs must be in dotted-decimal notation, with four groups of three decimal digits, separated by periods. Leading zeros in groups can be omitted.

Range: 0.0.0.0 - 255.255.255.255

Examples:

  • 1.1.1.1
  • 10.234.0.62

5. Invalid IPv6 Address

Error Message:
Invalid IPv6 address: "<input>".
Details:

The IPv6 address input is not a valid IPv6 address. Accepted inputs must be eight groups of four hexadecimal digits, separated by colons. Leading zeros in groups can be emitted. Consecutive groups of all zeros can be replaced by a double colon.

Range: 0000:0000:0000:0000:0000:0000:0000:0000 - ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff

Examples:

  • 2001:0db8:0000:0000:0000:ff00:0042:8329
  • 2001:0db8::ff00:0042:8329
  • 2001:db8::ff00:42:8329

6. Invalid IP Address

Error Message:
Invalid IP address: "<input>".
Details:

The IP address input is not a valid IPv4 or IPv6 address.

7. Invalid TTL

Error Message:
Invalid TTL: "<input>", must be a number between 30 and 2147483647.
Details:

Time-to-live must be a number in the range [30, 2147483647].

8. Invalid Batch Record Type

Error Message:
Invalid Batch Record Type: "<input>", valid record types for batch changes include <valid record types>.
Details:

The DNS record type is not currently supported for batch changes.

9. Zone Discovery Failed

Error Message:
Zone Discovery Failed: zone for "<input>" does not exist in VinylDNS. If zone exists, then it must be created in VinylDNS.
Details:

Given an inputName, VinylDNS will determine the record and zone name for the requested change. For most records, the record names are the same as the zone name (apex), or split at at the first ‘.’, so the inputName ‘rname.zone.name.com’ will be split into record name ‘rname’ and zone name ‘zone.name.com’ (or ‘rname.zone.name.com’ for both the record and zone name if it’s an apex record). For PTR records, there is logic to determine the appropriate reverse zone from the given IP address.

If this logic cannot find a matching zone in VinylDNS, you will see this error. In that case, you need to connect to the zone in VinylDNS. Even if the zone already exists outside of VinylDNS, it has to be added to VinylDNS to modify records.

10. Record Already Exists

Error Message:
Record "<input>" Already Exists: cannot add an existing record; to update it, issue a DeleteRecordSet then an Add.
Details:

A record with the given name already exists, and cannot be duplicated for the given type.

11. Record Does Not Exist

Error Message:
Record "<input>" Does Not Exist: cannot delete a record that does not exist.
Details:

A record with the given name could not be found in VinylDNS. If the record exists in DNS, then you should sync the zone for that record to bring VinylDNS up to date with what is in the DNS backend.

12. CNAME Conflict

Error Message:
CNAME conflict: CNAME record names must be unique. Existing record with name "<name>" and type "<type>" conflicts with this record.
Details:

A CNAME record with the given name already exists. CNAME records must have unique names.

13. User Is Not Authorized

Error Message:
User "<user>" is not authorized.
Details:

User must either be in the admin group for the zone being changed, or have an ACL rule.

14. Record Name Not Unique In Batch Change

Error Message:
Record "<name>" Name Not Unique In Batch Change: cannot have multiple "<type>" records with the same name.
Details:

Certain record types do not allow multiple records with the same name. If you get this error, it means you have illegally input two or more records with the same name and one of these types.

15. Invalid Record Type In Reverse Zone

Error Message:
Invalid Record Type In Reverse Zone: record with name "<name>" and type "<type>" is not allowed in a reverse zone.
Details:

Not all record types are allowed in a DNS reverse zone. The given type is not supported.

FULL-REQUEST ERRORS

Fail-request errors cause the batch change processing to abort immediately upon encounter.

  1. Batch Change Is Empty
  2. Change Limit Exceeded
  3. Batch Change Not Found
  4. Malformed JSON Errors

1. BATCH CHANGE IS EMPTY

HTTP RESPONSE CODE
Code description
422 Unprocessable Entity - the batch does not contain any changes, thus cannot be processed.
ERROR MESSAGE:
Batch change contained no changes. Batch change must have at least one change, up to a maximum of <limit> changes.
DETAILS:

There were no changes found in the create batch change request. A batch must contain at least one change and no more than 20 changes.

2. CHANGE LIMIT EXCEEDED

HTTP RESPONSE CODE
Code description
413 Request Entity Too Large - the batch size exceeds the maximum number of single changes, currently set to 20.
ERROR MESSAGE:
Cannot request more than <limit> changes in a single batch change request
DETAILS:

The number of change inputs in the create batch change request exceeds the max change input limit threshold, which is currently set to 20.

3. BATCH CHANGE NOT FOUND

HTTP RESPONSE CODE
Code description
404 Not Found - batch change not found for specified ID in get batch change request.
ERROR MESSAGE:
Batch change with id <id> cannot be found
DETAILS:

The batch ID specified in the get batch change request does not exist.

4. MALFORMED JSON ERRORS

DETAILS:

If there are issues with the JSON provided in a batch change request, errors will be returned (not in a by-change format) and none of the batch change validations will run.

EXAMPLE ERROR MESSAGES:
{
   "errors": [
      "Missing BatchChangeInput.changes"
   ]
}

{
   "errors": [
      "Missing BatchChangeInput.changes.inputName",
      "Missing BatchChangeInput.changes.type",
      "Missing BatchChangeInput.changes.ttl"
   ]
}

{
   "errors": [
      “Invalid RecordType”
   ]
}