> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overwatchapp.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overwatch API error responses and HTTP status codes

> Overwatch API error format, HTTP status codes (401–422), and how to handle limit-reached and subscription errors in your integration.

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:

```json theme={null}
{
  "error": "Unauthorized"
}
```

Some errors include additional fields:

```json theme={null}
{
  "error": "Monitor limit reached",
  "upgrade": true
}
```

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "error": "Forbidden"
}
```

See [Authentication](/api-reference/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.

```json theme={null}
{
  "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).

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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.