Consistent Errors

Category: Response Design

Description

Error responses with the same status code and content type must use consistent schema definitions across the entire API. Inconsistent error formats make error handling more complex and API usage more difficult.

What It Checks

This rule validates that error responses (4xx and 5xx status codes) maintain consistency throughout your API specification. It checks:

• All 4xx error responses (client errors)
• All 5xx error responses (server errors)
• Error response schemas grouped by status code and content type
• Whether multiple different schemas are used for the same error code and content type combination

The rule builds a mapping of status codes to content types to schemas, and flags any combinations where multiple different schemas exist for the same status code and content type.

Why It Matters

Consistent error responses are critical for API usability and maintainability:

• Simplified client code: Developers can write a single error handler for each status code instead of handling multiple formats
• Reduced confusion: Clients know exactly what error structure to expect for each HTTP status code
• Better tooling support: Code generators and SDK builders can create type-safe error handling
• Improved debugging: Consistent error formats make it easier to log, monitor, and debug issues across your API

Examples

Good ✅

paths:
  /users:
    post:
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /orders:
    post:
      responses:
        '400':
          description: Invalid order data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'  # Same schema
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'  # Same schema

components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: "VALIDATION_ERROR"
        message:
          type: string
          example: "The request contains invalid data"
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              error:
                type: string

Bad ❌

paths:
  /users:
    post:
      responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  error_code:
                    type: integer

  /orders:
    post:
      responses:
        '400':
          description: Invalid order
          content:
            application/json:
              schema:
                # Different schema for same 400 + application/json!
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
                  timestamp:
                    type: string

  /products:
    get:
      responses:
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string

  /categories:
    get:
      responses:
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                # Different schema for same 500 + application/json!
                type: object
                properties:
                  message:
                    type: string
                  stack:
                    type: string

Configuration

This rule has no configuration options. It is either enabled or disabled.

How to Fix

1. Create a shared error schema in your components/schemas section:

   components:
     schemas:
       ErrorResponse:
         type: object
         required:
           - code
           - message
         properties:
           code:
             type: string
           message:
             type: string
           details:
             type: object
   

2. Reference the same schema for all error responses with the same status code:

   # Before - inline schemas
   responses:
     '400':
       content:
         application/json:
           schema:
             type: object
             properties:
               error: string
   
   # After - shared reference
   responses:
     '400':
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/ErrorResponse'
   

3. Apply consistently across your entire API specification:

   • All 400 responses should use the same schema
   • All 401 responses should use the same schema
   • All 404 responses should use the same schema
   • All 500 responses should use the same schema
   • And so on for each status code you use

4. Consider different content types separately:

   • It's acceptable to have different schemas for application/json vs application/xml
   • But all application/json 400 errors should use the same schema
   • And all application/xml 400 errors should use the same (XML) schema

Common Patterns

Standard Error Response Structure

components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: "VALIDATION_ERROR"
        message:
          type: string
          description: Human-readable error message
          example: "The request contains invalid data"
        details:
          type: object
          description: Additional context about the error
          additionalProperties: true
        timestamp:
          type: string
          format: date-time
          description: When the error occurred

Validation Error with Field Details

components:
  schemas:
    ValidationErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            errors:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
                  code:
                    type: string

Related Rules

• Rule 8: Response Error Codes - Ensures errors use appropriate HTTP status codes
• Rule 35: Code 204 Empty - Ensures 204 responses are empty and other 2XX responses have bodies
• Rule 75: Consistent Naming Conventions - Enforces naming consistency across API components