Error Handling

ZopNight uses standard HTTP status codes and returns structured error responses.

Error Response Format

When an error occurs, the API returns a JSON response with an error field:

{
  "error": {
    "message": "schedule not found"
  }
}

Code	Meaning	Common Causes
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request body, missing required fields, validation errors
`401`	Unauthorized	Missing, invalid, or expired JWT token
`403`	Forbidden	Insufficient permissions or accessing another organization's resources
`404`	Not Found	Resource, schedule, or endpoint does not exist
`409`	Conflict	Duplicate resource, schedule name already exists
`429`	Too Many Requests	Rate limit exceeded — see Rate Limiting
`500`	Internal Server Error	Unexpected server error — retry with backoff
`502`	Bad Gateway	Gateway could not reach the backend service
`503`	Service Unavailable	Service is temporarily unavailable

Status	Action
4xx (except 429)	Do not retry. Fix the request and try again.
429	Back off and retry after the period indicated in the response.
500	Retry with exponential backoff (1s, 2s, 4s, 8s).
502/503	Retry with exponential backoff. The service may be restarting.

Idempotent Operations

POST endpoints for actions (start/stop) are idempotent. It is safe to retry these operations without risk of double-execution.

HTTP 401
{
  "error": {
    "message": "token has expired"
  }
}

Use the /auth/refresh endpoint to get a new access token.

HTTP 400
{
  "error": {
    "message": "invalid cron expression: '0 25 * * *'"
  }
}

HTTP 404
{
  "error": {
    "message": "resource not found"
  }
}

HTTP 429
{
  "error": {
    "message": "rate limit exceeded"
  }
}