Error codes reference

HostTracker uses two families of error codes:

• Check error codenames describe why a check failed (Timeout, DnsHostNotFound, Http 503). You see them in the check log, alerts, incidents and the API.
• API problem codes describe why an API request was refused (missing_scope, invalid_interval).

Check error codenames

Every failed check is classified into a short, stable English codename next to its full error message. The codename is what to filter, group and automate on; the message may be reworded. It appears in the API as error.codename on results and cause.codename on incidents, in webhook payloads as error.codename, in alert templates as [[errorcodename]], and in the v1 API as error.cn. For the most common ones in plain language, see Common check errors.

Fallback names

An error without a specific codename falls back to its raw type, with the code when there is one - for example SnmpError, SocketError, WebError or HTError (13). That is expected and still tells you the category.

HTTP status

Codename	Meaning
Http <code>	The final response had a failing HTTP status, for example Http 404, Http 500, Http 503.

CDN / origin errors (HTTP 520-530)

These statuses come from a CDN (Cloudflare and compatible) that could not get a usable answer from your origin server, so they get a name instead of a bare number.

Codename	Status	Meaning
CdnError	520	The CDN got an unexpected or empty response from the origin.
WebServerDown	521	The origin refused the CDN’s connection.
ConnectTimeout	522	The CDN’s connection to the origin timed out.
OriginUnreachable	523	The CDN could not reach the origin.
OriginTimeout	524	The origin accepted the connection but answered too slowly.
SslHandshakeFailed	525	TLS handshake between the CDN and the origin failed.
InvalidSslCert	526	The origin’s certificate is invalid.
RailgunError	527	The CDN’s Railgun connection to the origin was interrupted.
OriginDnsError	530	The origin’s hostname could not be resolved by the CDN.

Connection errors (socket level)

Codename	Meaning
DnsHostNotFound	The hostname could not be resolved.
DnsTryAgain	A temporary DNS failure - often clears by itself.
DnsNoData	The DNS server has no record of the requested type for the name.
ConnectTimeout	The connection attempt timed out.
ConnectionRefused	Nothing is listening on the host and port.
ConnectionReset	The connection was dropped by the other side.
ConnectionAborted	The connection was aborted before completing.
HostUnreachable	No route to the host.
NetworkUnreachable	No route to the host’s network.
HostDown	The host appears down at the network level.
AccessDenied	The connection was denied (often a local or firewall restriction).

HTTP client errors

Codename	Meaning
DnsResolveFailed	The domain name could not be resolved.
ConnectFailed	The connection to the server could not be made.
ConnectionBroken	The response ended early (unexpected end of data).
ConnectionClosed	The connection was closed unexpectedly.
SendFailed	The request could not be sent.
ProtocolError / ProtocolViolation	The response broke the HTTP protocol.
TlsCertRejected	The server’s certificate was rejected.
TlsHandshakeFailed	The TLS handshake failed.
Timeout	The request timed out.
ProxyDnsFailed	A configured proxy’s name could not be resolved.
NameNotResolved	The hostname could not be resolved (reported by the operating system).
InvalidArgument	The operating system rejected the request’s parameters.
UnknownError	An error with no more specific classification.

DNS errors

Codename	Meaning
DomainNotFound	The domain does not exist (NXDOMAIN).
DnsServerFailure	The DNS server failed (SERVFAIL).
DnsRefused	The DNS server refused the query.
DnsFormatError	The query was malformed.
DnsTimeout	The DNS query timed out.
BlockedResolution	The name resolved to a null address (0.0.0.0 or ::), which suggests blocking by a resolver.
UnexpectedIp	The resolved addresses did not match the expected ones.
NoPublicDns	No public DNS server could be reached to resolve the name.

TLS / certificate errors

Codename	Meaning
TlsCertRejected	The certificate was rejected.
CertExpired	The certificate has expired (or is not yet valid).
CertNameMismatch	The certificate does not cover the requested hostname.
CertRevoked	The certificate was revoked.
NoCert	No certificate was presented.
CertChainError	The certificate chain could not be validated.
WeakTlsProtocol	A weak or deprecated TLS version was negotiated.
WeakCipher	A weak cipher suite was negotiated.
CertParseError	The certificate’s expiry date could not be read.
TlsError	Another TLS problem.

Content and verdict

Codename	Meaning
KeywordsMissing	An expected keyword was not found in the response.
KeywordsPresent	A keyword that must be absent was found (older keyword mode).
PatternMismatch	The response did not match the expected pattern.
AssertFailed	One or more assertion rules failed; the message lists them.
PolicyViolation	A validation policy was violated.
ContentTooLarge	The response exceeded the monitor’s maximum size.
RedirectLoop	The request got stuck in a redirect loop.
UnexpectedResponse	The response was not what the check expected.

Checking agent errors

Codename	Meaning
PingFailed	Most or all ping attempts failed.
Timeout	The check timed out.
UnsupportedCheck	The location that ran it does not support this check type.
AgentError	An unhandled error on the checking agent.
AgentBusy	The checking agent was overloaded; the check is retried.
BadRequest	The check request was malformed.
BadSelector	An invalid selector (for example in a content check).
ValueError	A value in the check’s settings was invalid.
ServiceError	An internal service error.
InvalidUri	The monitored URL is invalid.
SystemError	An operating-system error on the agent.
UnsupportedNode	The location’s operating system is no longer supported.

Database, counter and SNMP

Codename	Meaning
DatabaseError	The database connection or query failed.
DbConditionFailed	The query result did not meet the configured condition.
CounterError	The counter (server load) check failed.
CounterOverload	The counter value exceeded the configured threshold.
SnmpError	The SNMP request failed.
SnmpConditionFailed	The SNMP value did not meet the configured condition.
SnmpProtocolError	An SNMP protocol error.
SnmpTransportError	An SNMP transport error.

Domain, blacklist and Web Risk

Codename	Meaning
Blacklisted	The domain or IP is listed on a checked blacklist.
NotBlacklisted	Informational: not listed.
DomainUnresolvable	The domain is not registered or its registration data cannot be found.
DomainExpired	The domain registration has expired.
WebRiskThreat	Google Web Risk flagged the URL.

Browser checks (Transaction, Page speed, Content check)

Codename	Meaning
NameNotResolved	The hostname could not be resolved.
ConnectionRefused	The connection was refused.
ConnectionReset	The connection was reset.
ConnectTimeout	The connection or page load timed out.
HostUnreachable	The host could not be reached.
TlsCertRejected	The page’s certificate was rejected.
TlsHandshakeFailed	The TLS handshake failed.
NoResponse	No response was received.
Http <code>	The page returned this HTTP status.
Timeout	The browser check timed out.
BrowserError	Another browser error.

Security checks

Codename	Meaning
ShellShock	The server appears vulnerable to Shellshock.
Poodle	The server appears vulnerable to POODLE.
Logjam	The server appears vulnerable to Logjam.
Vulnerable	Another vulnerability was detected.

REST API v2 error codes

Every refused API request answers an RFC 9457 application/problem+json document with a stable code, the HTTP status and an errors[] array carrying the members listed below. Each code has a page at https://api2.host-tracker.com/problems/{code}. Branch on code; retry only the codes in the last group.

Fix the request

Code	Status	Meaning	Members in errors[]
malformed_request	400	The body could not be parsed.	pointer, detail, reason
idempotency_key_required	400	This operation needs an Idempotency-Key header.	endpoint
method_not_allowed	405	The method is not allowed on this path.	method, allowed
payload_too_large	413	The body is larger than the endpoint accepts.	limit, actual
unsupported_media_type	415	The body’s content type is not accepted.	contentType, supported
validation_failed	422	The body or query is not valid; reason says why (required, unknown_member, wrong_type, empty, duplicate, …).	pointer, parameter, value, allowed, reason, expected, min, max, didYouMean, …
unknown_parameter	422	A query parameter the endpoint does not define.	parameter, allowed, didYouMean
unknown_enum_value	422	A value outside the field’s allowed set.	pointer, value, allowed, didYouMean
unknown_expand	422	An expand token the endpoint does not offer.	value, allowed, didYouMean
unknown_field	422	A fields name the row does not have.	value, allowed, didYouMean
invalid_cursor	422	The paging cursor is not valid.	parameter, reason
invalid_limit	422	limit is outside 1-500.	value, min, max
invalid_range	422	The time window is invalid or too wide.	from, to, maxSpan, reason
invalid_interval	422	The check interval is not allowed for the account.	value, allowed
interval_below_type_floor	422	The interval is below the monitor type’s minimum.	type, minInterval
invalid_alert_delay	422	The alert delay is not a supported value.	value, allowed
invalid_settings	422	A value inside settings is not valid for the monitor type.	pointer, value, allowed, reason, expected, min, max
invalid_url	422	The URL cannot be used (required, malformed, scheme_not_allowed, destination_not_allowed).	pointer, value, reason
unknown_pool	422	The location pool does not exist.	pool, valid
insufficient_agents	422	Not enough monitoring locations match the selection.	required, matched, perPool
unknown_contact_ref	422	A subscription names a contactRefs entry no inline contact declares.	ref, declared
unknown_event_type	422	A webhook event outside the catalogue (or a callback-only event).	value, allowed
unsupported_report_channel	422	Reports can only go to email contacts.	contactType, supported
contact_type_not_creatable	422	Contacts of this type cannot be created here.	type, successor, allowed
monitor_type_discontinued	422	The monitor type is discontinued.	type, successor
unsupported_monitor_type	422	The operation is not available for this monitor type.	type, supported
type_immutable	422	A resource’s type cannot be changed.	current, requested
credential_write_only	422	The masked value read back from a credential cannot be written.	pointer
filter_required	422	The operation refuses to run without a filter.	parameter, hint
too_many_items	422	More items than the operation accepts.	limit, actual
invalid_confirmation_code	422	The contact confirmation code is wrong or expired.	attemptsLeft, expiresAt

Fix the account state

Code	Status	Meaning	Members in errors[]
invalid_token	401	The token is missing, malformed or expired.	reason (missing, invalid)
insufficient_balance	402	Not enough balance to send the message (SMS, voice).	balance, required, currency
missing_scope	403	The token lacks the scope.	required, granted
insufficient_rights	403	A subaccount lacks the right.	required, granted
ip_not_allowed	403	The caller’s address is not on the token’s allow-list.	clientIp
package_limit	403	The plan does not allow this (count or feature).	feature, used, allowed
package_interval_conflict	403	No interval satisfies both the monitor type and the plan.	type, minInterval, allowed
url_blacklisted	403	This URL is not accepted for monitoring.	url, scope
not_found	404	The resource does not exist (or is not yours).	resource, id
duplicate_monitor	409	A monitor with this URL and type already exists.	existingId, key
duplicate_contact	409	A contact with this type, address, gateway and delay already exists.	existingId, key
duplicate_resource	409	A resource with this key already exists.	existingId, key
contact_already_confirmed	409	The contact is already confirmed.	contactId, confirmedAt
selection_mismatch	409	A bulk delete’s selection changed since it was validated.	expected, actual
idempotency_key_conflict	409	The key was used for a different body, or the first call is still running.	key, reason, retryAfterSeconds
job_not_cancellable	409	The job already finished.	state
job_not_resumable	409	The job is not interrupted, or its kind cannot resume.	state, reason
monitor_run_refused	409	The monitor cannot be run right now.	reason, retryAfter, nextAllowedAt

Wait and retry

Code	Status	Meaning	Members in errors[]
quota_exceeded	429	The scope’s API quota for the window is spent. Wait until resetAt.	limit, remaining, resetAt
rate_limited	429	A short-window throttle. Wait Retry-After seconds.	limit, window, retryAfter
internal_error	500	Unexpected server error. Quote traceId to support.	traceId
upstream_error	502	A service the request depends on failed.	service, retryAfter
service_unavailable	503	Temporarily unavailable.	service, retryAfter

Related

• Common check errors and what they mean
• REST API v2
• Why is it down
• Assertion language reference