# Errors

Standard error format and HTTP status codes returned by the AyeWatch API.

Source: https://ayewatch.ai/documentation/errors

## Error Response Shape

All API errors return a consistent JSON structure:

```json
{
  "error": {
    "message": "Human-readable error description",
    "status": 400
  }
}
```

The `status` field mirrors the HTTP response status code. Always check the HTTP status first, then
read `error.message` for details.

## HTTP Status Codes

| Status | Name | When it occurs |
| --- | --- | --- |
| `400` | Bad Request | The request body or parameters are invalid or missing required fields. Also returned when the interval you asked for isn't unlocked by your plan. |
| `401` | Unauthorized | API key is missing, malformed, or does not exist. |
| `403` | Forbidden | The API key is valid, but the account is on Free Preview, or the request would exceed a plan limit such as active topics or monitoring capacity. |
| `404` | Not Found | The requested resource (topic ID) does not exist or belongs to another user. |
| `409` | Conflict | The request conflicts with your existing topics — either a topic with that name already exists, or another change to your topics was still being applied. The second case is safe to retry after a short pause. |
| `429` | Too Many Requests | Rate limit exceeded for this API key. Wait for the number of seconds given in the Retry-After header before retrying. |
| `500` | Internal Server Error | An unexpected error occurred on our side. Please retry or contact support. |

## Example Error Responses

401 — Missing or invalid API key:

```json
{
  "error": {
    "message": "Unauthorized",
    "status": 401
  }
}
```

403 — Upgrade required:

```json
{
  "error": {
    "message": "API access requires a paid plan",
    "status": 403
  }
}
```

403 — Max API keys reached:

```json
{
  "error": {
    "message": "You have reached the maximum of 10 active API keys",
    "status": 403
  }
}
```

403 — Plan limit reached:

```json
{
  "error": {
    "message": "Not enough monitoring capacity for Hourly right now. Slow or remove a topic, or upgrade.",
    "status": 403
  }
}
```

404 — Topic not found:

```json
{
  "error": {
    "message": "Topic not found",
    "status": 404
  }
}
```

409 — Duplicate topic name:

```json
{
  "error": {
    "message": "A topic with this name already exists",
    "status": 409
  }
}
```

409 — Another change was in progress (retry):

```json
{
  "error": {
    "message": "Timed out waiting for another monitor change to finish.",
    "status": 409
  }
}
```

## Need Help?

If you encounter a persistent 500 error or unexpected behavior, please [contact support](https://ayewatch.ai/contact)
with the request details and timestamps.