OpenAPI: Standard Error Response Definitions

Defining Standard Error Responses in OpenAPI

Consistent error responses are essential for API usability. The RFC 7807 "Problem Details for HTTP APIs" format is the industry standard.

Error Schema (RFC 7807)

components:
  schemas:
    Error:
      type: object
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          description: URI reference identifying the error type
        title:
          type: string
          description: Short, human-readable summary
        status:
          type: integer
          description: HTTP status code
        detail:
          type: string
          description: Human-readable explanation
        instance:
          type: string
          description: URI reference for this specific occurrence
    ValidationError:
      type: object
      required:
        - type
        - title
        - status
        - errors
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: The field that failed validation
              message:
                type: string
                description: What went wrong
              code:
                type: string
                description: Machine-readable error code

Reusable Response Components

components:
  responses:
    BadRequest:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    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'

Using Reusable Responses

Reference these in your path operations:

responses:
  '400':
    $ref: '#/components/responses/BadRequest'
  '401':
    $ref: '#/components/responses/Unauthorized'
  '404':
    $ref: '#/components/responses/NotFound'

Common HTTP Status Codes for APIs

Code	Meaning	When to Use
400	Bad Request	Validation errors, malformed JSON
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Authenticated but insufficient permissions
404	Not Found	Resource does not exist
409	Conflict	Duplicate resource or state conflict
422	Unprocessable Entity	Semantically invalid request
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server failure