Overwatch API error responses and HTTP status codes

When a request fails, the Overwatch API returns a JSON body alongside an appropriate HTTP status code. Your client should check the status code first, then inspect the body for a human-readable message and any machine-readable codes.

Error object shape

All error responses include at minimum an error field:

{
  "error": "Unauthorized"
}

Some errors include additional fields:

{
  "error": "Monitor limit reached",
  "upgrade": true
}

{
  "error": "Check interval not allowed on your plan",
  "code": "interval_too_short"
}

Field	Type	Description
`error`	string	Human-readable description of the error.
`code`	string	Machine-readable error code, present on some validation and billing errors.
`upgrade`	boolean	`true` when the error is caused by a plan limit. Prompt the user to upgrade.

HTTP status codes

Status	Meaning
`200 OK`	The request succeeded. The response body contains a `data` field.
`201 Created`	The resource was created successfully.
`401 Unauthorized`	No valid API key was provided, or the key has expired.
`402 Payment Required`	Your organization does not have an active subscription.
`403 Forbidden`	Your API key’s role does not permit this action.
`404 Not Found`	The requested resource does not exist or belongs to a different organization.
`422 Unprocessable Entity`	The request body failed validation, or a plan limit has been reached.

Common errors in detail

401 Unauthorized

Returned when the Authorization header is missing, malformed, or contains a key that does not exist or has expired.

{
  "error": "Unauthorized"
}

Check that you are passing the header as Authorization: Bearer ow_live_sk_... and that the key has not expired.

402 Payment Required

Returned when your organization lacks an active subscription and the endpoint requires one. This occurs on POST /api/v1/monitors and POST /api/v1/alerts, which are write operations gated behind billing.

{
  "error": "No active subscription",
  "code": "no_subscription"
}

403 Forbidden

Returned when your API key’s role is insufficient for the requested operation. For example, a viewer key cannot create or delete resources; an admin key cannot manage API keys.

{
  "error": "Forbidden"
}

See Authentication for a full breakdown of what each role can do.

404 Not Found

Returned when the resource ID in the URL does not match any resource in your organization. Overwatch returns 404 rather than exposing whether a resource exists in a different organization.

{
  "error": "Not found"
}

422 Unprocessable Entity

Returned for two distinct situations: Validation errors — the request body is missing required fields or contains invalid values (for example, an unsupported monitor type or alert channel type).

{
  "error": "Channel type \"PAGERDUTY\" is not currently supported. Allowed: WEBHOOK, SLACK, DISCORD, TEAMS, EMAIL"
}

Plan limit reached — you have hit the maximum number of monitors or alert channels allowed on your current plan. These responses include "upgrade": true.

{
  "error": "Monitor limit reached",
  "upgrade": true
}

When you receive a 422 with upgrade: true, the only way to proceed is to upgrade your plan from the Overwatch dashboard.

Overview

Endpoints

Overwatch API error responses and HTTP status codes

Error object shape

HTTP status codes

Common errors in detail

401 Unauthorized

402 Payment Required

403 Forbidden

404 Not Found

422 Unprocessable Entity

​Error object shape

​HTTP status codes

​Common errors in detail

​401 Unauthorized

​402 Payment Required

​403 Forbidden

​404 Not Found

​422 Unprocessable Entity

Error object shape

HTTP status codes

Common errors in detail

401 Unauthorized

402 Payment Required

403 Forbidden

404 Not Found

422 Unprocessable Entity