API error codes

Every error response has success: false and an error object with a machine-readable code, a human-readable message, optional details and the request_id of the request (also sent as the X-Request-Id header: quote it when you contact support). Switch on code, not on message. The HTTP status of a code never changes inside /v1, new codes can appear, so ignore codes you do not know.

{
  "success": false,
  "error": {
    "code": "RECORD_NOT_FOUND",
    "message": "Record not found or access denied",
    "request_id": "3f6c1e0a-7d8b-4b7e-9c1a-2f3e4d5c6b7a"
  }
}

An unknown path answers 404 NOT_FOUND. A 429 carries Retry-After (seconds) and the RateLimit and RateLimit-Policy headers.

Error codes

CodeStatusMeaning
ACCESS_DENIED403Admin access required
ACCOUNT_FROZEN403Restricted Mode: the account is frozen, suspended or pending deletion
ACCOUNT_NOT_ACTIVATED403Account not activated
ACCOUNT_NOT_FOUND404Account not found
ADD_DOMAIN_FAILED400The zone could not be added
ALERT_RULE_LIMIT_REACHED403Alert rule limit of the plan reached
AMOUNT_MISMATCH400Amount verification failed
APEX_NOT_ALLOWED_ON_FREE_DOMAIN403Apex and wildcard records are not allowed on free shared domains
API_ERROR400Generic API error (no more specific code)
API_KEY_LIMIT400API key limit of the plan reached
API_KEY_NOT_FOUND404API key not found
API_KEY_REQUIRED403The operation needs an API key, not a session token
ATTACH_VIEW_FAILED400The view could not be attached to the zone
AUDIT_PERMISSION_DENIED403The team role may not read the audit log
AUTH_FAILED401Authentication failed (wrong credentials, missing or invalid token)
BATCH_FAILED422One or more operations of the batch failed, nothing was changed (details.errors lists them all)
BILLING_PERMISSION_DENIED403Only the owner or a billing member may top up the wallet
BILLING_PROFILE_REQUIRED400Billing details are incomplete for an invoice
BULK_LIMIT_EXCEEDED400Too many records in one bulk request
CERT_DATA_MISSING500Certificate data is not available
CERT_NOT_ACTIVE409The certificate is not active
CERT_REQUEST_FAILED422The certificate order was refused
CHECKOUT_ERROR500Creating the checkout failed
CNAME_AT_APEX_NOT_ALLOWED422A CNAME is not allowed at the zone apex (it would replace the SOA and NS records)
CNAME_CONFLICT422A CNAME cannot coexist with other records at the same name
CONTENT_TOO_LONG400The record content is longer than 65535 bytes
CURRENCY_MISMATCH400The currency does not match the account billing currency
DAILY_SPEND_LIMIT_EXCEEDED402The daily spend limit of the API key is exhausted
DATABASE_ERROR500A database error occurred
DNSSEC_ALREADY_ENABLED409DNSSEC is already enabled for this zone
DNSSEC_INVALID_ALGORITHM400Unsupported DNSSEC algorithm
DNSSEC_NOT_ENABLED409DNSSEC is not enabled for this zone
DNS_LIMIT_EXCEEDED403Free account host limit reached
DOMAIN_CHECK_FAILED500The availability check failed
DOMAIN_EXISTS409Domain already exists in system
DOMAIN_NOT_AVAILABLE409The domain is not available for registration
DOMAIN_NOT_FOUND404Domain not found
DOMAIN_STILL_ACTIVE403A registered domain that is still valid cannot be removed
DOMAIN_UNAVAILABLE409The domain is not available
DPAY_API_ERROR502Payment provider error
DPAY_CONNECTION_ERROR502Payment provider unreachable
DPAY_REGISTRATION_FAILED502Payment provider refused to register the payment
EMAIL_REQUIRED400E-mail address is required
EMPTY_CART400Cart is empty
EMPTY_CONTENT400Record content is required
EMPTY_RRSET422An RRset needs at least one record; use DELETE to remove it
FORBIDDEN403Not allowed for this role or key
HOMOGRAPH_NOT_ALLOWED_ON_FREE_DOMAIN422This host name mixes scripts or contains look-alike, invisible or symbol characters and is not allowed on free shared domains
HOMOGRAPH_RISK422This name mixes scripts or contains look-alike, invisible or symbol characters and cannot be registered
INSUFFICIENT_BALANCE402Wallet balance too low for the operation
INSUFFICIENT_FUNDS400Wallet funds are not enough
INSUFFICIENT_SCOPE403The API key lacks the required scope
INTERNAL_ERROR500Unexpected server error
INVALID_AMOUNT400The amount is outside the allowed range
INVALID_BASE_NAME400Invalid base name
INVALID_CAA400The content of the CAA record is not valid
INVALID_CDNSKEY400The content of the CDNSKEY record is not valid
INVALID_CDS400The content of the CDS record is not valid
INVALID_CONTENT400Record content must be a string
INVALID_CSR422The certificate signing request is not valid
INVALID_CURRENCY400Unsupported currency
INVALID_CURSOR422Invalid or expired cursor
INVALID_DNAME400The content of the DNAME record is not valid
INVALID_DOMAIN400Invalid domain format
INVALID_DOMAIN_FORMAT400Invalid domain format
INVALID_DS400The content of the DS record is not valid
INVALID_EMAIL400A valid e-mail address is required
INVALID_HOSTNAME400The host name is not valid
INVALID_HTTPS400The content of the HTTPS record is not valid
INVALID_IP400Not a valid IPv4 address
INVALID_IPN400The payment notification is not valid
INVALID_IPV6400Not a valid IPv6 address
INVALID_LIMIT422limit must be between 1 and the maximum page size
INVALID_LOC400The content of the LOC record is not valid
INVALID_MX400The MX host name is not valid
INVALID_NAPTR400The content of the NAPTR record is not valid
INVALID_NETWORK400The network must be CIDR, for example 203.0.113.5/32
INVALID_OPENPGPKEY400The content of the OPENPGPKEY record is not valid
INVALID_PARAMS400, 422A query or body parameter is not valid
INVALID_PASSWORD403Incorrect password
INVALID_PHONE400The phone number is not valid
INVALID_PRIO400The priority of a record must be an integer between 0 and 65535
INVALID_PTR_CONTENT400PTR content must be a fully qualified name
INVALID_QUERY400The search query is too short
INVALID_RECORD_TYPE400Unknown DNS record type
INVALID_REQUEST400The request body must be a JSON object
INVALID_SOA400The content of the SOA record is not valid
INVALID_SOURCE400Unknown source
INVALID_SRV400The content of the SRV record is not valid
INVALID_SSHFP400The content of the SSHFP record is not valid
INVALID_SVCB400The content of the SVCB record is not valid
INVALID_SYNC_CHANGE400Each sync change requires a name, a type and a valid action (add, update or remove)
INVALID_TLSA400The content of the TLSA record is not valid
INVALID_TOTAL400Order total must be greater than 0
INVALID_TOTP_CODE403The two-factor code is wrong
INVALID_TTL400TTL outside the range any plan allows (1 to 86400)
INVALID_TXT400The content of the TXT record is not valid (a value is at most 4096 bytes)
INVALID_TYPE400Unknown record type
INVALID_URI400The content of the URI record is not valid
INVALID_USER_ID400Invalid user ID
INVALID_UUID400The transaction UUID is not valid
INVALID_VIEW_LABEL400A view label is required
INVALID_WEBHOOK400Invalid webhook data
INVALID_ZONE400The zone cannot be used for this operation
INVOICE_DOWNLOAD_FAILED502The invoice PDF could not be retrieved
INVOICE_NOT_AVAILABLE404No invoice for this transaction
IP_NOT_ALLOWED403The API key may not be used from this address
JWT_REQUIRED403The operation needs a session token, not an API key
MAGIC_LINK_INVALID401The sign-in link is invalid or expired
MANDATE_ALREADY_ACTIVE409Auto-renewal is already enabled
MANDATE_FAILED400The recurring mandate has failed, it cannot be charged
MANDATE_NOT_FOUND404Recurring mandate not found
METHOD_NOT_ALLOWED405The path exists but not for this method (see the Allow header)
MISSING_DOMAIN400Domain name missing in order item
MISSING_ZONE_DATA400zone_data is required
MONITOR_LIMIT_REACHED403Monitor limit of the plan reached
MOVE_VIEW_FAILED400The zone could not be moved to the view
NAME_NOT_ALLOWED403The name is outside the zones allowed for the API key
NETWORK_ALREADY_IN_VIEW409The network is already in this view
NETWORK_ALREADY_TAKEN409This network overlaps a range already claimed by another account
NETWORK_NOT_FOUND404Network not found for this view
NETWORK_NOT_PUBLIC400The network is not public address space
NOT_EU_COUNTRY400VIES validation is available for EU countries only
NOT_FOUND404Resource not found (also an unknown path)
NOT_MANAGED400AuthInfo is only available for domains registered through no-ip.pl
NO_PAID_PLAN400No paid plan on the account
NO_PROVIDER_AVAILABLE400No payment provider for the currency
NO_TLDS_SPECIFIED400At least one TLD must be specified
NULL_MX_CONFLICT422A null MX (RFC 7505) must be the only MX record of its name
ORDER_NOT_FOUND404Order not found
PARENT_ZONE_DELEGATED_TO_OTHER_ACCOUNT409The parent zone delegates this name to another account
PARENT_ZONE_OWNED_BY_OTHER_ACCOUNT409The parent zone belongs to another account and does not delegate to our name servers
PASSKEY_ERROR400The passkey assertion is not valid
PASSWORD_REQUIRED400Password is required to delete account
PAYMENT_CREATION_FAILED502The payment could not be created
PDNS_ERROR400, 503DNS backend error
PDNS_NOT_CONFIGURED500DNS backend not configured
PDNS_UNREACHABLE503DNS backend unreachable
PERSONAL_DATA_REQUIRED400Personal data is required to register a domain
PLAN_NOT_FOUND404Plan not found
PLAN_UPGRADE_REQUIRED403The feature needs a higher plan
PRICING_ERROR500No price configured for the product
PROFILE_EXISTS409A profile with this label already exists
PROFILE_INCOMPLETE400The account profile is incomplete for a registration
PROFILE_LIMIT_EXCEEDED403Profile limit of the plan reached
PROFILE_NOT_FOUND404Profile not found
PROVIDER_NOT_FOUND400Payment provider not found
PROVIDER_UNSUPPORTED400The payment provider does not support the currency
PTR_ZONE_MISMATCH400The PTR name does not fit the reverse zone
RATE_LIMIT_EXCEEDED429Too many requests; see Retry-After
RECORD_EXISTS409DNS record already exists
RECORD_LIMIT_REACHED403Record limit of the plan reached
RECORD_NOT_FOUND404Record not found or access denied
RECURRING_CHARGE_ERROR500Charging the recurring mandate failed
RECURRING_INIT_ERROR500Starting the recurring mandate failed
RECURRING_INIT_FAILED502The payment provider refused the recurring mandate
REGISTRAR_ERROR502The registrar did not do what was asked
REGISTRATION_FAILED400The registrar refused the registration
RENEWAL_FAILED400The registrar refused the renewal
RRSET_NOT_EDITABLE422This RRset is managed by the platform (SOA)
RRSET_NOT_FOUND404RRset not found
RRSET_SINGLE_VALUE422A CNAME, ALIAS or DNAME RRset has exactly one record
RRSET_TOO_LARGE422The TXT values of one name together exceed 16384 bytes
SIBS_API_ERROR502Payment provider error
SIBS_CHECKOUT_FAILED502The payment provider could not create the checkout
SIBS_CONNECTION_ERROR502Payment provider unreachable
SYNC_EMPTY502The registrar returned no TLDs
SYNC_FAILED500Synchronising prices failed
TEAM_MEMBER_EXISTS409This member already has that role/zone combination
TEAM_MEMBER_LIMIT_REACHED403Team member limit of the plan reached
TEMPLATE_CONFLICT409The zone holds records that contradict the template
TEMPLATE_EXISTS409A template with this name already exists
TEMPLATE_LIMIT_EXCEEDED403Template limit of the plan reached
TEMPLATE_NOT_FOUND404Template not found
TEST_TOO_SOON429A test was sent a moment ago; see Retry-After
TLD_NOT_AVAILABLE400Registration for this TLD is not available
TOKEN_REQUIRED400A token is required
TOTP_ALREADY_ENABLED409Two-factor authentication is already enabled
TOTP_ERROR422Two-factor setup failed
TOTP_INVALID422The two-factor code is wrong
TOTP_NOT_ENABLED422Two-factor authentication is not enabled
TOTP_REQUIRED403The change widens an API key and needs a two-factor code
TRANSACTION_NOT_FOUND404Transaction not found
TRANSFER_FAILED400The registrar refused the transfer
TRANSFER_LOCK_NOT_SUPPORTED409The registrar has no transfer lock for this TLD
TTL_BELOW_PLAN_MINIMUM422TTL is below the minimum of the plan (details.min_ttl, details.plan)
TTL_MISMATCH422Records of one name and type must share one TTL
UNKNOWN_ITEM_TYPE400Unknown order item type
USER_NOT_FOUND404User not found
VALIDATION_ERROR422, 400A field is missing or not valid; see error.details
VIEW_EXISTS409You already have a view with this label
VIEW_HAS_ZONES409The view still serves zones (use force)
VIEW_NOT_FOUND404View not found
VIEW_UNCHANGED409This zone already uses this view
WEBHOOK_LIMIT_REACHED403Webhook limit of the plan reached
WFIRMA_API_ERROR502Invoicing service error
WFIRMA_CONNECTION_ERROR502Invoice PDF could not be fetched
WFIRMA_UNEXPECTED_RESPONSE502Unexpected answer from the invoicing service
ZONE_HAS_VIEWS409The zone is attached to views (use force)
ZONE_LIMIT_REACHED403Zone limit of the plan reached
ZONE_LOCKED403This zone is locked on your current plan
ZONE_NOT_FOUND404Zone not found or access denied
ZONE_TOO_BROAD400The reverse zone is too broad for the plan
ZONE_UNDER_PLATFORM_ZONE409Sub-zones of a platform zone cannot be created

Related