# Error Handling Architecture {#error-handling-architecture}


Standardized error handling patterns across the API layer.


## Global Exception Filter {#global-exception-filter}


All unhandled exceptions are caught by the global exception filter:

```typescript
@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();

    const status =
      exception instanceof HttpException
        ? exception.getStatus()
        : HttpStatus.INTERNAL_SERVER_ERROR;

    response.status(status).json({
      statusCode: status,
      message: this.getErrorMessage(exception),
      timestamp: new Date().toISOString(),
    });
  }
}
```


## Standard Error Responses {#standard-error-responses}



### 400 Bad Request {#400-bad-request}


Validation errors return field-level details:

```json
{
  "statusCode": 400,
  "message": ["email must be an email", "name should not be empty"],
  "error": "Bad Request"
}
```


### 401 Unauthorized {#401-unauthorized}


```json
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```


### 403 Forbidden {#403-forbidden}


Missing permissions:

```json
{
  "statusCode": 403,
  "message": "You do not have permission to access this resource"
}
```


### 404 Not Found {#404-not-found}


```json
{
  "statusCode": 404,
  "message": "Record not found"
}
```


### 409 Conflict {#409-conflict}


Duplicate records:

```json
{
  "statusCode": 409,
  "message": "Email already in use"
}
```


### 429 Too Many Requests {#429-too-many-requests}


Rate limiting:

```json
{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}
```


## Custom Exceptions {#custom-exceptions}


```typescript
// Usage in services
throw new NotFoundException("Employee not found");
throw new ForbiddenException("Insufficient permissions");
throw new ConflictException("Email already exists");
throw new BadRequestException("Invalid date range");
```


## Error Logging {#error-logging}


All 5xx errors are logged with full stack traces. 4xx errors are logged at `warn` level.


## Related Pages {#related-pages}


- [Request Lifecycle](https://sourcey-gauzy.pages.dev/architecture/request-lifecycle/index.md) — request flow
- [API Error Handling](https://sourcey-gauzy.pages.dev/api/error-handling/index.md) — client error handling