API reference

Errors

Dominder uses conventional HTTP status codes. Successful responses are always 2xx; anything else is an error. Every error response is a JSON envelope with anerrorfield (and optionally a longermessage).

Error envelope

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error":   "Invalid hostname.",
  "message": "(only present on some endpoints for extra context)"
}

Status codes

CodeMeaningTypical causes
200OKStandard successful response.
201CreatedReturned fromPOST /domains on success.
400Bad RequestInvalid hostname, unknown record type, missing required field, interval out of range, non-JSON body.
401UnauthorizedMissing or invalid API key. Check yourAuthorization header.
402Payment RequiredYour subscription is notactive ortrialing. Resolve via thebilling page.
404Not FoundThe resource id doesn't exist on your account, or the route doesn't exist.
409ConflictYou already have a domain with that hostname. Delete or update the existing one instead.
500Internal Server ErrorSomething unexpected broke on our side. Retry after a short delay; if it persists, contact support.

Example error responses

400 Bad Request - bad hostname
{ "error": "Invalid hostname." }
400 Bad Request - bad record type
{ "error": "Unsupported record type \"WXYZ\"." }
401 Unauthorized - missing key
{ "error": "Missing API key" }
402 Payment Required
{
  "error":   "Subscription required",
  "message": "Your account does not have an active subscription. Please subscribe to use the API."
}
404 Not Found - unknown domain id
{ "error": "Domain not found." }
409 Conflict - duplicate hostname
{ "error": "This hostname is already being monitored." }

Writing a good client

  • Always checkresponse.ok (or the equivalent in your HTTP client) before parsing the body - the body might still be JSON but it's an error envelope, not your expected shape.
  • On401, don't retry with the same key - fix it.
  • On402, surface the message to your operators so they know to update billing. Retrying is pointless until the subscription is active.
  • On5xx, retry with exponential backoff - but don't hammer us.