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

# Errors

> HTTP status codes and error response format for the Warrn API.

The Warrn API uses conventional HTTP status codes to indicate the success or failure of a request. Codes in the `2xx` range indicate success, codes in the `4xx` range indicate a problem with the request (a missing field, an invalid API key, a resource that doesn't exist), and codes in the `5xx` range indicate a problem with Warrn's servers.

Every error response includes a human-readable `message` describing what went wrong, so you can surface useful diagnostics in client integrations and CI logs without having to map status codes by hand.

## Error Response Format

When a request fails, the API returns a JSON object with an error message:

```json theme={null}
{
  "message": "Alert not found with alias: my-alert-alias"
}
```

For OpsGenie-compatible endpoints, errors include a `requestId` for tracing:

```json theme={null}
{
  "message": "Failed to create alert. Please try again.",
  "took": 0.0,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

## HTTP Status Codes

| Code  | Meaning                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------- |
| `200` | Request succeeded                                                                                  |
| `201` | Resource created                                                                                   |
| `400` | Bad request — invalid JSON, missing required fields, or integration disabled                       |
| `401` | Unauthorized — missing or invalid API key                                                          |
| `403` | Forbidden — API key lacks required permission, or IP not in allowlist                              |
| `404` | Resource does not exist — alert, team, or service could not be located                             |
| `422` | Validation error — field value out of range (e.g. invalid severity)                                |
| `429` | Rate limit exceeded — wait and retry                                                               |
| `500` | Internal server error — retry with exponential backoff and contact support if the problem persists |

## Common Errors

### Invalid API key

```
HTTP 401 Unauthorized
```

Check that you're passing the key as `Authorization: Bearer warrn_xxx`. The key must start with `warrn_`.

### Permission denied

```
HTTP 403 Forbidden
```

Your API key has `read` permission but the endpoint requires `write`. Create a new key with the correct permission level.

### Invalid severity

```
HTTP 422 Unprocessable Entity
```

The `severity` field must be one of: `low`, `medium`, `high`, `critical`.