OpenAPI Responses — Defining Success and Error Response Structures

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

OpenAPI responses define the HTTP status codes, headers, and body schemas that an API endpoint returns for both successful operations and error conditions.

What You'll Learn

• Defining responses for different status codes
• Response headers and their purposes
• Reusable response components

Why It Matters

Complete response definitions enable clients to handle every possible API response correctly, reducing runtime errors and support requests.

Code Examples

responses:
  "200":
    description: Successful response
    headers:
      X-Request-ID:
        schema:
          type: string
          format: uuid
        description: Request correlation ID
      X-RateLimit-Remaining:
        schema:
          type: integer
        description: Remaining API calls
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/User"
        examples:
          user_example:
            value:
              id: 1
              name: Alice
              email: alice@example.com

  "201":
    description: Resource created
    headers:
      Location:
        schema:
          type: string
          format: uri
        description: URL of the created resource

  "400":
    description: Bad request
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Error"
        example:
          code: VALIDATION_ERROR
          message: Name is required

  "404":
    description: Resource not found
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Error"

  "500":
    description: Internal server error
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Error"

# Generating response examples from spec
def get_response_example(spec, path, method, status_code):
    responses = spec['paths'][path][method]['responses']
    response = responses.get(str(status_code), {})
    content = response.get('content', {}).get('application/json', {})
    schema = content.get('schema', {})
    return schema.get('example', 'No example available')

Common Mistakes

1. Only Defining 200 Responses

Always define 400, 401, 403, 404, and 500 responses.

2. Inconsistent Error Response Formats

All error responses should use the same schema across the entire API.

3. Missing Response Headers

Headers like X-RateLimit-Remaining and Location should be documented.

4. No Examples in Response Schemas

Examples help developers understand what the response looks like.

5. Using Generic Descriptions

"Successful response" is too vague. Describe what the response contains.

Practice Questions

1. What HTTP status codes should every endpoint document?
2. How do you define response headers in OpenAPI?
3. What is the Location header used for?
4. Why should error responses use a consistent format?
5. How do you provide response examples?

Answers:

1. At minimum 200, 400, 401, 404, 500.
2. In the headers field of each response object.
3. To tell the client the URL of a newly created resource.
4. So clients can write generic error handling code.
5. Using the example or examples field in the content.

Challenge: Define complete response objects for a payment API including success (200), insufficient funds (402), not found (404), and server error (500) with consistent error formats.

FAQ