Status codes

The DNScaster API uses standard HTTP response codes to indicate whether an API request succeeded or failed.

Status: 200
Request succeeded; payload is included.

Status: 201
Request to create a resource succeeded; payload is included.

Status: 202
Request accepted, but not completed and may or may not succeed.

Status may need to be verified at a later time.

Status: 204
Request succeeded; no payload.

Status: 302, 303, 307
Redirect to another location. Clients should be prepared to follow a limited number of redirects.

Status: 400
Bad request; generally a missing parameter, encoding error, or malformed request.

Status: 402
DNScaster subscription is not active or otherwise needs attention. Login to the management portal.

Status: 403
API authentication failed. This can be because authentication credentials were missing, incomplete, incorrect, or lack sufficient permission to perform the current request.

Status: 404
Resource not found or not accessible to the current user. The latter case means that you may receive a 404 instead of a 403 in certain instances.

Status: 405
Method not allowed. Resource URI is recognized, but the HTTP verb sent is not valid for it. For example, sending a POST when only a PUT is allowed for that URI. Can also be an invalid HTTP verb, such as POSST.

Status: 406
Request not acceptable. Returned if requesting an unavailable document content type. Ensure that a proper Accept: header is being sent.

Status: 409
There was a conflict when attempting to update the resource. Most often this is a failed attempt to delete a resource that is in a state that prevents it from being deleted at this time. Should return a validation error like 422.

Status: 415
Returned if submitting data using an unrecognized content-type (currently anything other than JSON or standard URL encoded form data).

Status: 417
Most commonly, returned when using one of .NET’s HTTP clients that automatically enable the expect header. In that case, set Expect100Continue = false.

Status: 422
Validation error. May be returned for POST, PUT, and DELETE operations.

{ "message" : "Validation failed",
  "errors" : ["Nameserver set is required."]
}

Status: 429
Rate-limiting thresholds have been exceeded. HTTP headers containing the current rate limiting status are included with 429 and 2xx responses. Exponential backoff is recommended.

RateLimit-Limit: 1234
RateLimit-Remaining: 0
RateLimit-Reset: Mon, 22 Apr 2021 20:00:00 GMT
Retry-After: 9

Retry-After is in seconds.

Status: 500, 502
An error happened on DNScaster’s side. Wait a few minutes and try again. Also ensure your request is properly formed.

Status: 503, 504
Service unavailable. This may be in response to heavy load, to exceeding rate-limiting thresholds, or server errors. Wait a few minutes and try again. Exponential backoff is recommended.

Additional Notes

Clients must read the actual HTTP status header (and other headers as appropriate) prior to attempting to interpret the JSON body payload. Payloads for errors (4xx, 5xx) are intended to be informative, but may change.