# 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](/troubleshooting/common-errors/).

:::note[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](/reference/assert-language/) 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](/integrations/rest-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](/troubleshooting/common-errors/)
- [REST API v2](/integrations/rest-api/#errors)
- [Why is it down](/incidents/why-is-it-down/)
- [Assertion language reference](/reference/assert-language/)