Error responses

Document possible error responses via the errors field (available in defineRoute and @DocRoute):

errors: {
  // Plain string — description only
  401: 'Missing or invalid Authorization header',

  // Object — description + error body schema
  422: {
    description: 'Validation failed',
    schema: s.object({ message: s.string(), field: s.string() }),
  },

  // Object — schema only
  500: { schema: s.object({ message: s.string() }) },
}

Error responses appear in each route's detail panel, colour-coded by class (amber for 4xx, red for 5xx), and are exported as saved example responses when downloading a Postman collection — so consumers see exactly what the 422 / 409 / 500 bodies look like.

In the OpenAPI export

Each declared status emits a full responses[N] entry with the schema — spec-driven mocks (including doctreen mock) can then return realistic error payloads when running with --error-rate.

NestJS

@Post()
@DocRoute({
  request:  { body: CreateUser },
  response: User,
  errors: {
    409: 'Email already in use',
    422: { description: 'Validation failed', schema: s.object({ message: s.string() }) },
  },
})
createUser(@Body() body: any) { /* ... */ }

Or compose with the granular decorator:

@DocErrors({ 409: 'Conflict', 422: 'Validation failed' })

In the OpenAPI export

NestJS

On this page