Error Codes

What failed requests look like, and the machine-readable error codes returned within monitoring data.

Request Errors

When a request fails, how it fails depends on where.

Situation	Response
The API key or secret is missing or invalid, or the account can't use the API (for example, an unverified email)	HTTP `401` with a JSON body `{ "detail": "..." }`. See Authentication.
Your plan doesn't include API access	HTTP `403` with a JSON body `{ "detail": "..." }`.
Too many failed authentication attempts from your IP address	HTTP `429` with a JSON body `{ "detail": "..." }`. While blocked, even valid credentials are rejected. Stop sending requests and wait before trying again.
The request reached the API but was refused or failed — for example invalid input, a read-only key, missing permission, a size limit, or a record that doesn't exist	HTTP `200` with a standard GraphQL `errors` array. Each entry has a readable `message` and a `path` to the failing field.
An invalid query or variable value, such as a value that isn't in an enum	An `errors` entry whose `message` says what is wrong.
An unexpected problem on our side	An `errors` entry with the message `Internal Server Error`. Retrying later usually works; if it keeps happening, contact Support.

{
  "data": null,
  "errors": [
    {
      "message": "This API grant is read-only; changes are not permitted.",
      "path": ["createSite"]
    }
  ]
}

Handling errors

Don't retry 401, 403, or an errors entry for invalid input, a read-only key, missing permission, or a record that doesn't exist. Retrying won't change the result; fix the request or the key first.
After a 429, wait before sending anything else.
Retry Internal Server Error later, with a growing delay.
Messages are meant for people, not for matching in code, and they can change with the request's Accept-Language header. Use the path of an errors entry, and to react to a failed check in your data, use the error codes below.

Some fields carry their own error object — a code enum plus a human-readable message — separate from whether the GraphQL request itself succeeded. A check's error is populated when that specific check (SSL, DNS, WHOIS, etc.) couldn't complete; the rest of the response is still valid, and the request returns normally.

query {
  getSite(domain: "acme.io") {
    ssl {
      error {
        code
        message
      }
      payload {
        notAfter
      }
    }
  }
}

If error is null, the check ran successfully — check payload instead.

Each code is described in the GraphQL schema, which you can read through introspection.

SSL

SslErrorCode — site.ssl.error.code, and on the SSL incident types.

enum SslErrorCode {
  SSL_CHAIN_VERIFICATION_FAILED
  SSL_UNEXPECTED_ERROR
  SSL_PEER_CERT_MISMATCH
  SSL_PEER_UNREACHABLE
  SSL_HANDSHAKE_FAILED
  SSL_CONNECTION_TIMEOUT
  SSL_CONNECTION_REFUSED
}

Certificates

CertificateErrorCode — site.certificate.error.code. See Site: Certificates.

enum CertificateErrorCode {
  CERTIFICATE_UNEXPECTED_ERROR
}

Domain

DomainErrorCode — site.whois.error.code, and on the domain incident types.

enum DomainErrorCode {
  WHOIS_DOMAIN_NOT_FOUND
  WHOIS_DOMAIN_UNEXPECTED_ERROR
  WHOIS_DOMAIN_SERVER_NOT_FOUND
  WHOIS_DOMAIN_SERVER_NOT_WORKING
  RDAP_DOMAIN_NOT_FOUND
  RDAP_DOMAIN_SERVER_NOT_FOUND
  RDAP_DOMAIN_INVALID_RESPONSE
  RDAP_DOMAIN_QUERY_FAILED
  RDAP_DOMAIN_SERVER_NOT_WORKING
  DOMAIN_QUERY_FAILED
}

DNS

Two levels: DNSRequestErrorCode covers the DNS lookup itself (site.dns.error.code); DnsErrorCode covers parsing issues on individual derived records (SPF, DMARC, BIMI, TLS-RPT, MTA-STS) within site.dns.payload.

enum DNSRequestErrorCode {
  DNS_REQUEST_DOMAIN_NOT_FOUND
  DNS_REQUEST_NO_NAMESERVERS
  DNS_REQUEST_NO_ANSWER
  DNS_REQUEST_TIMEOUT
  DNS_REQUEST_UNEXPECTED_ERROR
  DNS_REQUEST_NAME_TOO_LONG
}

enum DnsErrorCode {
  DNS_MULTIPLE_DMARC_ERROR
  DNS_INVALID_SPF_ERROR
  DNS_MULTIPLE_SPF_ERROR
  DNS_MULTIPLE_BIMI_ERROR
  DNS_MULTIPLE_TLS_RPT_ERROR
  DNS_INVALID_TLS_RPT_ERROR
  DNS_MULTIPLE_MTA_STS_ERROR
  DNS_INVALID_MTA_STS_ERROR
  DNS_RECORD_UNEXPECTED_ERROR
}

Main Page

MainPageErrorCode — site.mainPage.error.code.

enum MainPageErrorCode {
  MAIN_PAGE_UNEXPECTED_ERROR
  MAIN_PAGE_DOMAIN_MISMATCH
  MAIN_PAGE_REDIRECT_LIMIT_EXCEEDED
  MAIN_PAGE_CRAWLER_UNSUPPORTED_SCHEMA
  MAIN_PAGE_INVALID_URL
  MAIN_PAGE_CONNECTION_FAILED
}

Robots.txt

RobotsTxtErrorCode — site.robotsTxt.error.code.

enum RobotsTxtErrorCode {
  ROBOTS_TXT_NOT_FOUND
  ROBOTS_TXT_INVALID_SIZE
  ROBOTS_TXT_INVALID_FORMAT
  ROBOTS_TXT_UNEXPECTED_ERROR
}

RobotsTxtValidationErrorCode — code on each entry of messages in SiteRobotsTxtValid / SiteRobotsTxtInvalid.

enum RobotsTxtValidationErrorCode {
  EMPTY_CONTENT
  LOOKS_LIKE_HTML
  NO_VALID_DIRECTIVES
  MISSING_SEPARATOR
  EMPTY_DIRECTIVE
  RULE_WITHOUT_USER_AGENT
  NO_VALID_USER_AGENT_GROUP
  CONTENT_SIGNAL_WITHOUT_USER_AGENT
  CONTENT_SIGNAL_NO_VALUE
  CONTENT_SIGNAL_MISSING_EQUALS
  CONTENT_SIGNAL_UNKNOWN_SIGNAL
  CONTENT_SIGNAL_INVALID_VALUE
  CONTENT_SIGNAL_INVALID_USE_VALUE
  CONTENT_TOO_LARGE
}

Sitemap

Two levels: SitemapDiscoveryErrorCode covers discovering a domain's sitemap(s) (site.sitemap.error.code); SitemapErrorCode covers individual sitemap files/entries within findSiteSitemap / findSiteSitemapLink. See Site: Sitemap.

enum SitemapDiscoveryErrorCode {
  SITEMAP_ROBOTS_TXT_UNAVAILABLE
  SITEMAP_DIRECTIVE_NOT_FOUND
  SITEMAP_DISCOVERY_UNREACHABLE
}

enum SitemapErrorCode {
  SITEMAP_NOT_FOUND
  SITEMAP_TOO_LARGE
  SITEMAP_INVALID_FORMAT
  SITEMAP_UNREACHABLE
  SITEMAP_UNEXPECTED_ERROR
  SITEMAP_FILE_LIMIT_REACHED
  SITEMAP_LINK_LIMIT_REACHED
  SITEMAP_NESTED_INDEX_NOT_SUPPORTED
  SITEMAP_FILE_OUT_OF_SCOPE
  SITEMAP_URL_OUT_OF_SCOPE
}

Links

LinkCrawlerErrorCode — on individual findSiteLink items. See Site: Links.

enum LinkCrawlerErrorCode {
  LINK_CRAWLER_UNEXPECTED_ERROR
  LINK_CRAWLER_LIMIT_REACHED
}

Uptime

UptimeErrorCode — on findUptimeLinkRecord items and lastRecord. See Uptime.

enum UptimeErrorCode {
  UPTIME_STATUS_CODE
  UPTIME_TIMEOUT
  UPTIME_KEYWORD_MATCH
  UPTIME_TOO_MANY_REDIRECTS
  UPTIME_SSL
  UPTIME_CONNECTION
  UPTIME_REQUEST
  UPTIME_UNEXPECTED
}