Errors

The Zeitstrom API uses conventional HTTP response codes to indicate the success or failure of a request.

HTTP Status Codes

Code	Description
`200 OK`	The request succeeded.
`201 Created`	A new resource was created successfully.
`204 No Content`	The request succeeded with no response body (e.g. after a DELETE).
`400 Bad Request`	The request was invalid. Check the response body for validation details.
`401 Unauthorized`	No valid API token was provided.
`403 Forbidden`	The API token does not have permission for this action.
`404 Not Found`	The requested resource does not exist.
`405 Method Not Allowed`	The HTTP method is not supported for this endpoint.
`500 Internal Server Error`	Something went wrong on our end.

Error Response Format

Error responses include a detail field with a human-readable message:

Authentication Error (401)

{
  "detail": "Invalid token."
}

Permission Error (403)

{
  "detail": "You do not have permission to perform this action."
}

Not Found (404)

{
  "detail": "Not found."
}

Validation Errors

When a request fails validation, the API returns a 400 status with field-level error details:

Validation Error (400)

{
  "first_name": ["This field may not be blank."],
  "email": ["Enter a valid email address."]
}

For non-field errors, the response uses the non_field_errors key:

Non-Field Error (400)

{
  "non_field_errors": ["The combination of the provided fields is invalid."]
}

When a query parameter of a request is invalid — for example an unsupported ?order= field or a malformed filter value — the API returns a 400 status with the errors keyed under $query. Inside $query, each key is the name of the offending query parameter:

Invalid Order Field (400)

{
  "$query": {
    "order": [
      "Order field `email` is not allowed. Supported fields for this endpoint are `checkin`, `checkout`, `break_duration`, `work_duration`."
    ]
  }
}

Invalid Filter Value (400)

{
  "$query": {
    "daterange": ["Invalid format."]
  }
}

Structured Errors

Some validation errors are returned in a machine-readable format with a stable id, a params object with contextual values, and a human-readable message. Use the id to handle these errors programmatically. Values inside params are always serialized as strings:

Structured Error (400)

{
  "id": "MAX_FILE_SIZE_EXCEEDED",
  "params": {
    "current": "8388608",
    "maximum": "5242880"
  },
  "message": "Maximum file size of 5242880 bytes exceeded."
}