Skip to main content
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"
}
FieldTypeDescription
errorstringHuman-readable description of the error.
codestringMachine-readable error code, present on some validation and billing errors.
upgradebooleantrue when the error is caused by a plan limit. Prompt the user to upgrade.

​
HTTP status codes

StatusMeaning
200 OKThe request succeeded. The response body contains a data field.
201 CreatedThe resource was created successfully.
401 UnauthorizedNo valid API key was provided, or the key has expired.
402 Payment RequiredYour organization does not have an active subscription.
403 ForbiddenYour API key’s role does not permit this action.
404 Not FoundThe requested resource does not exist or belongs to a different organization.
422 Unprocessable EntityThe 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.