Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 37 ยท Paths, Schemas and Components

OpenAPI Responses: Status Codes, Headers and Error Shapes

Describe every outcome of an API call in OpenAPI: response objects, status codes, ranges, default, headers, empty bodies, error schemas and links.

A great API description answers not only "what do I send?" but also "what can come back?". Every operation lists its possible outcomes in the responses object, keyed by HTTP status code. This is the field generators and testers lean on the most, so it deserves care.

The responses object

YAML
responses:
  "200":
    description: The pet
    headers:
      ETag:
        description: Version of the resource
        schema: { type: string }
    content:
      application/json:
        schema: { $ref: "#/components/schemas/Pet" }
  "404":
    description: No pet with that id
    content:
      application/problem+json:
        schema: { $ref: "#/components/schemas/Problem" }
  default:
    description: Unexpected error
    content:
      application/json:
        schema: { $ref: "#/components/schemas/Error" }

Rules:

  • The operation must define at least one response, ideally the successful one.
  • Each response requires a description (what this outcome means).
  • Keys are quoted status codes: "200", "404". You can also use ranges "2XX", "4XX" (capital X).
  • default covers every status code that is not listed explicitly. It is usually the generic error.
  • Matching order: an exact code wins, then the range, then default.

Which codes to document

You do not have to list all HTTP codes. Document the ones a client must handle:

Situation Code Notes
Read succeeded 200 Body with the resource
Created 201 Add a Location header
Accepted for later 202 Asynchronous work
Success, nothing to return 204 No content
Bad input 400 / 422 Validation errors
Not logged in 401 See security schemes
Not allowed 403
Not found 404
Conflict 409 Duplicate, version clash
Too many requests 429 Add Retry-After
Server failed 5XX Use a range or default

Responses with no body

Omit content:

YAML
"204":
  description: Pet deleted
"201":
  description: Created
  headers:
    Location:
      description: URL of the new pet
      schema: { type: string, format: uri }

A shared error shape

Most APIs return the same structure for all errors, so define it once under components and reuse it (see components and $ref). A popular standard is Problem Details (RFC 9457, application/problem+json):

YAML
components:
  schemas:
    Problem:
      type: object
      required: [title, status]
      properties:
        type:   { type: string, format: uri }
        title:  { type: string }
        status: { type: integer }
        detail: { type: string }
        instance: { type: string }
  responses:
    NotFound:
      description: Resource not found
      content:
        application/problem+json:
          schema: { $ref: "#/components/schemas/Problem" }

Then each operation just writes "404": { $ref: "#/components/responses/NotFound" }.

Headers in responses

Document headers that clients must read: Location, ETag, rate-limit headers, pagination links, Retry-After. Do not list Content-Type; the content key covers it.

YAML
"429":
  description: Slow down
  headers:
    Retry-After:
      description: Seconds to wait
      schema: { type: integer }
    X-RateLimit-Remaining:
      schema: { type: integer }

links (an advanced, optional feature) describe how a value in one response can be used as input for another operation, for example the new pet's id from createPet feeding getPet:

YAML
"201":
  description: Created
  content:
    application/json:
      schema: { $ref: "#/components/schemas/Pet" }
  links:
    GetCreatedPet:
      operationId: getPet
      parameters:
        petId: "$response.body#/id"

Few tools use links today, but they make the relationships in a workflow explicit.

Pick the right response: a matcher

Clients and mock servers must choose the response description for a status code. This stand-in implements the exact, range, default fallback order and returns what a generated client would treat as success or error.

Python Stand-in: resolve a status code to its response

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Design advice

  1. Document at least one success and the errors a caller can fix (400, 401, 403, 404, 409).
  2. Use one error schema everywhere so generated clients need one error type.
  3. Prefer a specific code over default for cases you want clients to handle separately.
  4. Make the description meaningful: "No pet with that id" beats "Not found".
  5. If your API returns JSON, say so with application/json; do not leave content out for responses that have a body.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which field is mandatory in every response object?

    Every response needs a description; content, headers and links are optional.
  2. 2. A server answers 409 and the operation lists "200", "4XX" and default. Which entry applies?

    An exact code wins, then a range such as 4XX, then default.
  3. 3. How do you describe a 204 response?

    204 means no content, so the response object has just a description.
  4. 4. Why define one shared error schema?

    Consistency makes error handling simple for every caller.
  5. 5. How are status code keys written in YAML?

    Quote them; range keys use a capital X like "2XX".

Summary

  • responses maps status codes (or 2XX ranges, or default) to response objects.
  • Each response needs a description; content, headers and links are optional.
  • Reuse one error schema (Problem Details is a common choice) through components.
  • Document headers clients must read, such as Location, Retry-After, ETag.
  • Exact codes win over ranges, and ranges win over default.

Next: Schema objects and JSON Schema