OpenAPI Response Schema Patterns

Status codes are half of an API contract

An OpenAPI document is only as honest as its responses object. A path that returns 201 with a Location header but only documents 200 will mislead every consumer and code generator. This reference maps the HTTP status codes you actually return to the response schema, media type and headers OpenAPI 3.1 expects under each one.

How it works

Each status code carries semantics: some must have a body, some must not, and some require specific headers. The table below pairs every common code with its recommended OpenAPI media type (for example application/json for resources, application/problem+json for errors per RFC 9457), the schema shape to declare, and the headers worth documenting. Search by code or keyword to find the row.

A modern error convention is to define a single reusable component:

components:
  schemas:
    Problem:
      type: object
      properties:
        type: { type: string, format: uri }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
        instance: { type: string }

Then reference it under every error status with $ref: '#/components/schemas/Problem'.

Status codes that need special handling

A few codes trip up developers repeatedly:

201 Created must include a Location header pointing at the newly created resource. In OpenAPI, document it under headers:

'201':
  headers:
    Location:
      schema:
        type: string
        format: uri

204 No Content and 304 Not Modified carry no response body. Leave out the content key entirely — including an empty object causes some validators to warn, and generated clients may mishandle it.

422 Unprocessable Content is the correct status for validation errors on a well-formed request. Document a schema that lists per-field problems, not a generic message string. The RFC 9457 errors extension allows an array of sub-problems with their own detail and pointer fields.

429 Too Many Requests and 503 Service Unavailable should each document a Retry-After header. Without it, clients have no basis for backoff and will hammer the API harder.

Response documentation quick-reference

Tips and conventions

• 204 and 304 carry no body — omit the content object entirely.
• 201 should document a Location header pointing at the created resource.
• 429 and 503 should document a Retry-After header.
• Prefer enumerating concrete codes over relying solely on default.
• Keep error bodies consistent across the whole API using one component schema.