Error Handling
How errors are returned
Section titled “How errors are returned”Sicket uses normal HTTP status codes first.
The response body message then carries the business-specific explanation. When debugging an integration, read both:
- the HTTP status code
- the JSON response
message
Common statuses
Section titled “Common statuses”400 Bad Request
Section titled “400 Bad Request”Returned when the request is structurally invalid or missing required fields.
Typical examples:
- required field missing
- invalid pagination or filter value
- unsupported enum value
401 Unauthorized
Section titled “401 Unauthorized”Returned when the request is missing valid authentication.
Typical examples:
- no bearer token
- expired token
- malformed token
403 Forbidden
Section titled “403 Forbidden”Returned when the user is authenticated but does not have permission in the requested scope.
Typical examples:
- landlord tries to access another building
- tenant tries to access staff-only functionality
- user tries to manage knowledge-base content outside allowed scope
404 Not Found
Section titled “404 Not Found”Returned when the resource does not exist, or when the backend hides existence outside the caller’s scope.
Typical examples:
- ticket code does not exist
- building is not visible to the caller
- invitation token is invalid or unavailable
409 Conflict
Section titled “409 Conflict”Returned when the request is valid in structure but violates a domain rule or current resource state.
Typical examples:
- invitation already accepted
- duplicate or incompatible assignment state
- plan limit prevents creating another unit
429 Too Many Requests
Section titled “429 Too Many Requests”Returned when the request hits the rate limiter.
When present, clients should use headers such as Retry-After to back off cleanly.
Product-specific rule failures to expect
Section titled “Product-specific rule failures to expect”Examples of rule failures that matter in Sicket:
- tenant tries to create a ticket outside their assigned building or unit
- tenant account is not linked to a residential unit
- landlord tries to manage a building they are not assigned to
- knowledge-base feature is used on an ineligible subscription plan
- unit creation exceeds subscription limits
Integration guidance
Section titled “Integration guidance”External consumers should treat message as useful for debugging and operator visibility, but should not depend on exact string matching for core program flow unless they fully control the integration contract.
Prefer branching on:
- status code
- endpoint context
- known response shape