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.
401	Unauthorized	API key is missing, malformed, or does not exist.
403	Forbidden	The API key is valid but lacks permission — e.g. free plan or max API keys reached.
404	Not Found	The requested resource (topic ID) does not exist or belongs to another user.
429	Too Many Requests	Rate limit exceeded.
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 — Free plan

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

404 — Topic not found

json

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

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