Responses in OpenAPI — Status Codes, Schemas, and Headers

In this tutorial, you will learn about Responses in OpenAPI. We cover key concepts, practical examples, and best practices to help you master this topic.

OpenAPI responses define what an API returns for each HTTP status code, including response bodies with content types and schemas, headers, and links to related operations.

In this tutorial, you will learn how to define complete response objects for success and error scenarios, create reusable response definitions, and document response headers.

What You'll Learn

You will learn response object structure, status code conventions, response schemas, headers, and reusable patterns for consistent error responses.

flowchart LR
  A[Responses] --> B[Status Codes]
  A --> C[Content]
  A --> D[Headers]
  A --> E[Links]
  B:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Response Structure

Each response has a status code key, description, and optional content and headers:

responses:
  "200":
    description: Successful response
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/User"
    headers:
      X-Request-ID:
        schema:
          type: string

Status Code Conventions

Use the correct status code for each scenario:

responses:
  "200": # Success with body
    description: Resource retrieved
  "201": # Resource created
    description: Resource created
  "204": # Success, no body
    description: Resource deleted
  "400": # Client error
    description: Bad request
  "401": # Auth required
    description: Authentication required
  "404": # Not found
    description: Resource not found
  "409": # Conflict
    description: Resource conflict
  "422": # Validation error
    description: Validation failed
  "429": # Rate limit
    description: Too many requests
  "500": # Server error
    description: Internal server error

Reusable Error Responses

components:
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

Common Mistakes

1. Only documenting 200 — Missing error responses. Document 400, 401, 403, 404, 429, and 500 for every endpoint.
2. No description — Every response needs a description.
3. Inconsistent error format — Different error structures across endpoints. Use one Error schema.
4. No examples — Show what error responses look like.
5. Missing 204 for delete — DELETE should return 204 with no body.

Practice Questions

1. What is the required field in every response?
2. How do you define reusable error responses?
3. What status codes should every endpoint document?
4. How do you add headers to a response?
5. What is the default response used for?

Challenge

Create a complete response library for a payment API with schemas for success, validation errors, insufficient funds, Rate Limiting, and server errors. Include examples for each.

What's Next

In the next lesson, you will learn how to define schemas using JSON Schema.