Errors

Every error code the API returns, its HTTP status, and what to do about it.

This page lists the errors the API returns and what to do about each.

#The error body

Every error is JSON with an error code, and sometimes a field that says more:

JSON

{ "error": "monitor_limit", "limit": 5 }

limit accompanies a plan limit, feature names the plan feature a request needs, reason explains a rejected target, and request_id identifies a server error. An unexpected failure returns 500 with {"error":"internal_error","request_id":"..."}. Include the request_id when you write to us about it.

#Authentication and access

Code	Status	Meaning and what to do
`bad_json`	400	The request body is not valid JSON.
`unauthorized`	401	The `Authorization` header is missing or the key is invalid, expired, or revoked. Create a new key.
`session_required`	403	The endpoint is only available from the dashboard, such as creating keys or inviting members.
`forbidden`	403	Your role in the project does not allow this action, such as a viewer acknowledging an incident. See Roles and permissions.
`not_found`	404	The object does not exist, or the key's project cannot see it.
`rate_limited`	429	The account used its requests for this minute. Wait for `Retry-After` seconds.

A 429 response also carries RateLimit-Limit with the per-minute limit. The limit is 30 on the free plan, 120 on Pro, and 300 on Team, shared by every key on the account.

#Plan limits

Code	Status	Meaning and what to do
`monitor_limit`	403	The account has as many monitors as its plan allows. `limit` says how many. Delete one or upgrade.
`project_limit`	403	The account owns as many projects as its plan allows.
`domain_limit`	403	The account has as many custom domains as its plan allows.
`seat_limit`	409	The project's seats, including pending invites, are full.
`plan_required`	403	The request needs a higher plan. `feature` is `monitor_type` (API, DNS, Scheduler), `advanced_monitoring` (SSL, domain, JSON rules), `email_alerts`, `maintenance` (with the window `limit`), `escalation`, or `audit_log`. Incidents and status pages on a free project return it without a `feature`.

#Validation

Validation errors return 422.

Code	Meaning and what to do
`invalid_target`	The URL or host cannot be monitored. `reason` is `invalid_url`, `scheme_not_allowed`, `internal_host`, `private_ip`, `ip_not_allowed`, `ipv6_literal_blocked`, or `non_public_host`.
`invalid_headers`	More than 4 headers, a name outside letters, digits, and dashes, a value with a line break, a blocked name, or a kept header that was never stored.
`invalid_body`	A body over 8 KB, or a body with `GET` or `HEAD`.
`invalid_content_rules`	More than 4 rules, or a rule with an empty value or an invalid JSON path.
`keyword_needs_rule`	A keyword monitor needs at least one content rule.
`invalid_method`	A scheduler cannot use `HEAD` or `OPTIONS`.
`invalid_name`	A required name is empty.
`invalid_provider`, `invalid_url`, `invalid_email`	A channel's kind, URL, or address is not valid.
`invalid_window`, `invalid_recurrence`, `invalid_monitor_ids`	A maintenance window's end is not after its start, its recurrence is malformed, or its monitor list is not an array.
`invalid_subdomain`, `invalid_domain`	A status page handle or custom domain does not meet the rules in Publish a status page and Custom domain.
`invalid`	A field has the wrong type or is out of range, such as a string where a number belongs. `field` names it.

#Conflicts

Code	Status	Meaning and what to do
`channel_exists`	409	The project already has a channel of that kind. Edit it instead.
`status_page_exists`	409	The project already has a status page.
`subdomain_taken`	409	Another status page uses that handle.
`incident_resolved`	409	The incident is resolved and takes no more updates.
`already_member`	409	The invited address already belongs to the project.

#What's next?

REST API: authentication and the first calls.
Plans and limits: every limit behind the plan errors.