Skip to content

Error responses in OpenAPI: describing 4xx and 5xx with problem details

Last checked and updated

Describe failures as carefully as success: for each operation, the error statuses a client can meet, each with a body schema. Use one error format for the whole API, defined once under components and referenced everywhere. The format most APIs can adopt as it is, is problem details (RFC 9457), with the media type application/problem+json.

One schema, shared responses

components:
  schemas:
    Problem:
      type: object
      required: [type, title, status]
      properties:
        type:
          type: string
          format: uri-reference
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
  responses:
    NotFound:
      description: The resource does not exist
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
paths:
  /pets/{id}:
    get:
      responses:
        "200":
          description: The pet
        "404":
          $ref: "#/components/responses/NotFound"
        default:
          description: Any other error
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"

The RFC makes no member mandatory; requiring type, title and status is this description's own, stricter choice. default covers every status that is not listed. 4XX and 5XX are also valid keys, for a whole range; an exact code takes precedence over a range.

The members of a problem

MemberMeaning
typeA URI that identifies the kind of problem; the thing a client should switch on
titleA short, fixed description of that kind
statusThe HTTP status code, repeated in the body
detailAn explanation of this occurrence
instanceA URI for this occurrence, where there is one

An API may add members: a list of field errors for a validation failure is the usual one.

What it looks like from a mock

With an example on the 404, a mock generated from the description returns it when asked for that status:

$ curl -i http://127.0.0.1:4655/pets/p9 -H 'Prefer: code=404'
HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{"type":"https://api.example.com/problems/not-found","title":"Pet not found","status":404,"detail":"No pet has the id p9."}

so a client's error handling can be built and tested before the server exists. The file behind these runs declares 200 and 404 for this operation. A status the operation does not declare cannot be requested, and the mock says which ones exist, itself in problem-details form:

$ curl -i http://127.0.0.1:4655/pets/p9 -H 'Prefer: code=500'
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{"declared":["200","404"],"type":"https://apigit.com/mock/problems/unknown-status","title":"The operation does not declare this status","status":422,"detail":"The operation does not declare status 500. Declared: 200, 404."}

declared is an extension member, as the RFC allows. A default response does not change this: the mock answers a requested code only when that code, or a range such as 4XX that contains it, is declared.

Tools notice the gap

A readiness score for AI agents counts operations that document an error response. Before and after adding the 404 above to one of three operations:

$ apigit score ex.yaml
ex.yaml  89 / 100
  0 of 3  Operations document an error response

$ apigit score err.yaml
err.yaml  93 / 100
  1 of 3  Operations document an error response

An agent or a generated client that only knows the 200 has no schema for anything else: it cannot tell a missing resource from a failed validation.

Mistakes to avoid

  • A different error shape per operation. Clients then need error handling per call.
  • Errors with status 200 and an error field in the body. HTTP clients, caches and monitoring treat them as success.
  • default as the only response. The success case then has no schema of its own.
  • A description without content: the status is documented, the body is not.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish