Topic

Error contracts / HTTP exceptions → stable JSON

Definition

An API error contract is a stable JSON response shape returned for every failed request, produced here by mapping thrown HTTP exceptions through a single global exception filter.

In simpler words

No matter what breaks, clients get the same kind of error object back — so the frontend can show a message without guessing the shape each time.

Center this on a global exception filter (an AllExceptionsFilter) and a shared ApiErrorBody error shape.

Open official example (opens in new tab)

After this you can

Read the shared ApiErrorBody shape
Explain how correlationId connects a client error to server logs
Choose the HTTP exception that matches a failure

One filter, one shape

Definition

AllExceptionsFilter is a global, catch-all Nest exception filter that inspects any thrown exception, derives a status, error label, message, and optional field-level details, and serializes an ApiErrorBody with a correlationId sourced from the request.

In simpler words

It does not decide business rules — it only standardizes how a thrown exception becomes a response body.

HttpException subclasses — NotFoundException, ForbiddenException, BadRequestException from ValidationPipe, and others — map their status and message straight into the shape.

An unexpected non-HTTP error becomes a generic 500 with a safe message; the real error is logged server-side, never sent to the client.

ApiErrorBody

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": ["title must be longer than or equal to 1 characters"],
  "details": [{ "field": "request", "message": "..." }],
  "correlationId": "..."
}

message is always a string or string[]; the frontend never has to branch on a fifth shape.

Throw the exception that matches the failure

Definition

Choosing an HTTP exception class is choosing the contract a client will see, so a thrown exception should represent the actual failure — not-found, validation, authorization — rather than a generic error.

In simpler words

A missing ticket, an invalid role, and a bad body are different failures and should produce different statuses.

TicketsService.get and .remove throw NotFoundException when a row does not exist — the controller stays free of if-not-found branching.

Never catch and swallow an exception just to return 200 with an error flag in the body; that breaks the contract for every consumer.

Service throws, filter formats

async get(id: string) {
  const ticket = await this.ticketsRepo.findOne({ where: { id } });
  if (!ticket) throw new NotFoundException('Ticket not found');
  return this.toResponse(ticket);
}

The filter turns this into { statusCode: 404, error: "Not Found", message: "Ticket not found", correlationId }.

Keep in mind

Let the exception filter be the only place that builds an error response.
Pick 404/400/401/403 by what actually failed, not by convenience.
Never leak stack traces or raw driver errors to clients in production.

Test

Check your understanding

At least 10 questions — mix of concept, syntax, practical, and logic. Score ≥80% (enforced by the API) to save progress.

Checking your session…

15 questions · concept 5 · syntax 3 · practical 4 · logic 3

1. How do errors become stable JSON here?

Concept

Each controller invents its own error JSONErrors return HTML pages for the frontendAllExceptionsFilter maps exceptions to ApiErrorBody with statusCode, error, message, correlationId500s always include full stack traces for clients

2. Why a single filter?

Syntax

Clients can rely on one error schema across 400/401/403/404/500So each controller can override the error shape per routeSo the ValidationPipe no longer needs to runSo error responses can be cached at the CDN

3. Should 500 responses expose stack traces to browsers?

Practical

No — keep client messages safe; log details server-sideYes — clients need the stack to display a useful error pageYes, but only the top frame of the stackOnly when NODE_ENV is production, to aid support

4. What is correlationId for?

Logic

Uniquely identify the authenticated user across requestsAct as a CSRF token for the next requestTie a client error to server logs for the same requestDeduplicate identical error messages in the response

5. Who should build error JSON?

Concept

Each handler’s own try/catch returning its own shapeThe ValidationPipe, which formats all error responsesA middleware that runs before the guardsThe global exception filter — not each route ad hoc

6. What does NotFoundException become?

Practical

A 404 with the shared error body shapeA 400 with the shared error bodyA 204 No Content responseA 404 but with a raw string body, bypassing the filter

7. What does UnauthorizedException become?

Syntax

403 with the shared error body401 with the shared error body400, since credentials are malformed401 but as plain text, not the shared body

8. What does ForbiddenException become?

Logic

401 with the shared error body404, to hide the resource from the client403 but without the correlationId field403 with the shared error body

9. Why include an error field besides message?

Concept

To duplicate the statusCode as a stringTo carry the stack trace for the clientA stable machine-oriented label alongside human messageTo hold the correlationId in a second place

10. Can filters catch errors from guards and pipes?

Practical

Yes — thrown errors from those stages still hit filtersNo — only exceptions thrown inside the route handler are caughtOnly exceptions from pipes; guard errors bypass the filterOnly if each guard and pipe is wrapped in try/catch

11. What response does the client get from this code?

Conceptintermediate

const ticket = await this.repo.findOneBy({ id });
if (!ticket) throw new NotFoundException('Ticket not found');

A 200 with an empty bodyA 404 with the shared error body of statusCode, error, message, correlationIdA 500 because throwing crashes the handlerA redirect to the login page

12. What is wrong with this error response?

Syntaxadvanced

catch (e) {
  return res.status(500).json({ message: e.message, stack: e.stack });
}

It leaks stack traces to clients; log details server-side and return a safe messageIt should use 400 instead of 500e.stack must be JSON.stringify-ed firstIt is fine because members cannot read stacks

13. Why are these two controllers a problem?

Practicalintermediate

// controller A
return res.json({ err: 'bad' });
// controller B
return res.json({ error: { message: 'bad' } });

res.json cannot send error objectsBoth must use status 200Errors should be returned as plain stringsInconsistent error shapes force clients to special-case each route; centralize in a filter

14. Does this filter also format errors thrown by guards and pipes?

Logicadvanced

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(ex, host) { /* build ApiErrorBody */ }
}

No — only errors thrown inside handlers are caughtNo — guard errors bypass filters entirelyYes — exceptions from guards and pipes are caught by the global filter tooOnly if @Catch lists each exception type

15. What statusCode appears in the error body for this throw?

Conceptintermediate

throw new ForbiddenException('Admins only');

401400500403

Checking your session…