Error Handling
The Offly API uses standard HTTP status codes and returns structured error responses.
Error response format
All error responses follow a consistent JSON structure:
Error Response
{
"error": {
"code": "validation_error",
"message": "Start date is required",
"details": { "field": "start_date" }
}
}| Field | Description |
|---|---|
| code | A machine-readable error code |
| message | A human-readable description of the error |
| details | Additional context (optional, varies by error type) |
Common error codes
| Status | Code | Description |
|---|---|---|
| 400 | bad_request | The request body is malformed or missing required fields |
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | The API key does not have the required scope for this action |
| 404 | not_found | The requested resource does not exist |
| 409 | conflict | The request conflicts with the current state (e.g. duplicate leave request) |
| 422 | validation_error | The request body failed validation (see details for field-level errors) |
| 429 | rate_limited | Too many requests — see Rate Limits |
| 500 | internal_error | An unexpected error occurred on our side — retry or contact support |
Handling errors
- •Always check the HTTP status code before parsing the response body
- •Use the
codefield for programmatic error handling - •Display the
messagefield to users when appropriate - •For 429 responses, respect the
Retry-Afterheader - •For 500 errors, implement exponential backoff with retries