Error Handling

ZopNight uses standard HTTP status codes and returns structured JSON error responses. Reference for status codes, retry strategy, and common error scenarios.

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 a string error field:

json

{
"error": "schedule not found"
}

HTTP Status Codes

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

Retry Strategy

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.

Common Error Scenarios

Expired Token

json

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

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

Invalid Request Body

json

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

Resource Not Found

json

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

Rate Limited

json

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