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
| Member | Meaning |
|---|---|
type | A URI that identifies the kind of problem; the thing a client should switch on |
title | A short, fixed description of that kind |
status | The HTTP status code, repeated in the body |
detail | An explanation of this occurrence |
instance | A 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
errorfield in the body. HTTP clients, caches and monitoring treat them as success. defaultas the only response. The success case then has no schema of its own.- A
descriptionwithoutcontent: the status is documented, the body is not.