MUST

MUST define 400, 404, and 500 responses

Every operation MUST define 400, 404, and 500 responses and include at least one example.
This ensures proper client error handling
as per RFC 9457.

Invalid Example

responses:
  '400':
    description: Bad request
  '500':
    $ref: '#/components/responses/UnexpectedError'

Valid Example

responses:
  '400':
    description: Bad request
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/ProblemDetails'
        examples:
          missing-param:
            summary: Missing parameter
            value:
              title: "Missing parameter"
              status: 400
              detail: "Required query parameter 'foo' is missing"
  '404':
    $ref: '#/components/responses/NotFound'
  '500':
    $ref: '#/components/responses/UnexpectedError'

UKHSA Guidelines Error Handling

---

Published: 30 May 2025
Last updated: 14 August 2025
Page Source