Exceptions
Exceptions (atlas.exceptions) is the package containing the default exception classes across Atlas.
It provides a structured and consistent error-handling model that unifies how different layers — Controller, Service, and Repository — communicate operational failures.
Below are the descriptions of each exception.
HttpError
Bases: Exception
HttpError is the base class for all HTTP-aware exceptions in the Atlas framework. It defines the standard structure for errors that can be serialized into HTTP responses.
Attributes:
| Name | Type | Description |
|---|---|---|
message |
str
|
Human-readable error message. |
statusCode |
int
|
Associated HTTP status code (default: 500). |
details |
Optional[str]
|
Additional technical information about the error. |
BadRequestError
Bases: HttpError
BadRequestError represents client-side input or request errors (HTTP 400). Typically raised when a request payload or parameter is invalid.
BusinessRuleValidationError
Bases: HttpError
BusinessRuleValidationError indicates that a domain or business rule was violated (HTTP 422). Used when input is valid syntactically but fails logical or contextual validation.
ConflictError
Bases: HttpError
ConflictError is raised when an operation cannot be completed due to a resource state conflict (HTTP 409). Commonly used for duplication or concurrency violations.
DatabaseError
Bases: HttpError
DatabaseError signals unexpected failures in the persistence layer (HTTP 500).
Includes a details field describing the underlying database or ORM error.
DependencyError
Bases: HttpError
DependencyError represents temporary failures in external dependencies or upstream services (HTTP 503). Useful for unavailable APIs, integrations, or infrastructure components.
InconsistentStateError
Bases: HttpError
InconsistentStateError is raised when a resource or entity enters an invalid or contradictory state (HTTP 409). Often used to indicate logical inconsistencies between related entities.
NotFoundError
Bases: HttpError
NotFoundError indicates that the requested resource or entity does not exist (HTTP 404). Commonly used for missing database records or invalid references.
UnauthorizedActionError
Bases: HttpError
UnauthorizedActionError is raised when an operation is forbidden due to insufficient permissions (HTTP 403). Typically used for access control enforcement and authorization checks.
IntegrationError
Bases: HttpError
IntegrationError represents a failure during communication with external services (HTTP 500). Useful for unexpected response formats, contract/schema mismatches, business-rule violations, or any other errors during integration processing.