Should every OpenAPI operation list a default response?

A default response is a good catch-all for unexpected errors, but listing the concrete codes you actually return (400, 401, 404, 422, 500) documents the contract far better. Use default only as a fallback for anything not enumerated.

What schema should errors use?

RFC 9457 problem details (application/problem+json) is the modern standard, with type, title, status, detail and instance fields. Define it once as a reusable component and reference it from every error status.

Do 204 and 304 carry a response body?

No. 204 No Content and 304 Not Modified must not include a message body, so their OpenAPI response should have no content object — only headers if relevant.

How do I document validation errors?

Use 422 Unprocessable Content (or 400) with a schema that lists per-field errors. A common shape is an errors array of objects with field and message, or the RFC 9457 errors extension.

Is this tool sending any request?

No. It is a static, browser-rendered reference table. It performs no network calls and logs nothing — purely an offline lookup.

OpenAPI Response Schema Patterns

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

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'.

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.