Errors

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

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.

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.

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
  }
}

If you encounter a persistent 500 error or unexpected behavior, please contact support with the request details and timestamps.