When updating a hostname, the response to the update syntax will be one of the return codes. If there is an error, clients should communicate to the user a brief description of the problem that the return code indicates. To make troubleshooting easier, generic error messages such as "Unable to update" should not be used.
If updating multiple hostnames, hostname-specific return codes are given one per line, in the same order as the hostnames were specified. Return codes indicating a failure with the account or the system are given only once.
Update Types
Successful Updates
There is only one return code which indicates a successful update. Code **good** indicates that the update was successful and that the IP address was changed in our system.
No Change Updates
A **nochg** indicates a successful update but the IP address or other settings have not changed. The only acceptable situation where this allowed is during client initialization when the host has already been set to the same IP address. Users may also be given the option to "force" an update. This can be used to verify the authentication credentials and the current IP address.
As this is fairly infrequent, repeated instances of **nochg** updates will result in the host being blocked. Users should not be allowed to repeatedly force updates.
While it is not expected that the clients will prevent users from doing this, the client itself should strenuously avoid performing updates which would result in this return result.
Fatal Updates
Any failed update attempt is fatal which means that all further updates will also fail until the user has taken some sort of corrective action. For this reason, any failed update attempt should cause the client to be disabled until the situation is corrected and the client is manually re-enabled by the user.
Additionally, because the update may fail for a number of different reasons, the client needs to provide some method of communicating with the user that the update has failed and why. Some suggestions include:
- Logging a message in the general log window for the router (assuming it has one)
- Logging a message to a log window specific to the Dyn Update Client
- Generating an error message to an email address configured by the user
- Communicating to an external process running on the users desktop
Many of these errors involve configuration mistakes within the client or inconsistencies between the client configuration and the user's account status; in all of those cases, the client must stop updating until the user has corrected the problem. Retrying the update automatically in those cases is abuse and may result in client blocks.
Account-Related Errors
The codes below indicate that the client is not configured correctly for the user's account. These return codes are given just once. The client must stop updating until the user confirms that the problem has been resolved.
badauth |
The supplied authentication credentials do not match a valid user account. |
|---|---|
!donator |
An option available only to credited users (such as offline URL) was specified, but the user is not a
credited user. If multiple hosts were specified, only a single !donator
will be returned.
|
Update Complete
The codes below indicate that the update of a hostname was completed successfully.
good |
The update was successful, and the hostname is now updated. |
|---|---|
nochg |
The update succeeded, but no settings changed because the supplied IP address and other settings already
match the current values. Repeated unnecessary nochg updates may be treated
as abuse and can cause the hostname to become blocked.
|
Note that, for confirmation purposes, **good** and **nochg** messages will be followed by the IP address that the hostname was updated to. This value will be separated from the return code by a space.
Hostname-Related Errors
The codes below indicate a problem with a specific hostname. The client must stop updating that hostname until the user confirms that the problem has been resolved.
notfqdn |
The hostname is missing or is not a fully qualified domain name (for example,
hostname.dyndns.org or example.com).
|
|---|---|
nohost |
The hostname does not exist in this account, or it cannot be updated through this request. |
numhost |
Too many hostnames were specified in a single update request. This code can also be returned when the requested hostname is ambiguous, such as when multiple A records and/or multiple AAAA records exist for the same hostname. This does not mean that having one A record and one AAAA record is a problem. |
abuse |
The hostname specified is blocked for update abuse. |
If no hostnames were specified, **notfqdn** will be returned once.
Agent-Related Errors
badagent |
The request was rejected because the client did not identify itself correctly, did not follow update client requirements, or used an unsupported HTTP method. |
|---|---|
good 127.0.0.1 |
Some non-compliant clients may receive good 127.0.0.1 as a compatibility
response even though the original request was ignored. Clients should send a compliant User-Agent and parse
responses carefully.
|
Server Error Conditions
The codes below indicate server errors that will have to be investigated. The client must stop updating and ask the user to contact Dyn support. The client must not resume updating until 30 minutes have passed or user confirms that the problem has been resolved.
dnserr |
The service could not complete the DNS update because of an internal DNS-side failure. Clients should stop retrying temporarily and ask the user to contact Dyn support if the problem continues. |
|---|---|
911 |
A temporary problem exists on Dyn's side, such as scheduled maintenance or an internal server issue. Clients should stop updating temporarily and retry later rather than retrying aggressively. |
Dynamic DNS API Specifications
Flow Diagram | Detect IP Change | Perform Update | Return Codes | Policies | Guidelines & Notes | Client Blocks | Test Account