Skip to content
Platform Status

Responses

Error Responses in OpenAPI best practices

Errors in OpenAPI

In OpenAPI, errors are typically represented as responses, with a clear body response structure and a status code in the range of 400-599 describing the error.

A well-designed error response should provide a clear and actionable message that helps the developer describe the error to a user.

Key elements of an error response

The status code and response body are the key elements of an error response.

Status code

HTTP response status codes play a vital role in describing the nature of errors. You should use appropriate codes to indicate the error type:

Status code
400
Meaning
Bad Request
Example use case
Input validation failed
401
Meaning
Unauthorized
Example use case
Missing or invalid authentication
403
Meaning
Forbidden
Example use case
Insufficient permissions
404
Meaning
Not Found
Example use case
Resource does not exist
413
Meaning
Payload Too Large
Example use case
File or request body exceeds limit
415
Meaning
Unsupported Media Type
Example use case
Invalid content type (for example, text or XML)
500
Meaning
Internal Server Error
Example use case
Unexpected server-side issue

HTTP response status codes

You can find a comprehensive list of HTTP response status codes for client errors (400-499) here and server errors (500-599) here.

Response body

The response body provides the client with additional information about the error that can be displayed to the user. It is recommended to use a structured schema that describes the error in a clear and actionable way. Here is an example:

{
  "error": "ValidationError",
  "message": "The provided file type is not supported.",
  "details": {
    "field": "fileType",
    "allowedValues": ["image/jpeg", "application/pdf"]
  }
}

An error response can have these common properties:

  • error: A machine-readable error code, such as ValidationError or AuthenticationFailed.

  • message: A human-readable description of the error.

  • details: Additional contextual information about the error, such as invalid fields or allowed values.

You can provide additional properties in the response body, such as the timestamp or trace ID, to help with debugging and tracking the error.

Defining error responses in an OpenAPI document

For standard API endpoints, error responses should be defined in the responses section of the OpenAPI document. You can use reusable components to standardize error schemas:

paths:
  /resource:
    get:
      summary: Retrieve a resource
      responses:
        '200':
          description: Successful operation
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/InternalServerError'


components:
  responses:
    BadRequestError:
      description: Invalid input provided
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          additionalProperties: true
          description: Additional error context
        timestamp:
          type: string
          format: date-time
        traceId:
          type: string
          description: Unique identifier for error tracing

RFC 9457 Problem Details for Errors

Standardizing error messages: RFC 9457 Problem Details

RFC 9457 is a standard for representing errors in REST APIs. Published in July 2023, it introduces a standardized, machine-readable, and actionable format for describing errors. While RFC 9457 is widely regarded as a best practice, it is important to note that it is not included in the OpenAPI Specification (OAS).

The Problem Details format for describing errors is JSON-based and specifies key properties that are either required, optional, or extensible. When serialized as JSON, the format uses the media type application/problem+json.

The core properties of the Problem Details format are:

  • type: A URI reference that identifies the problem type, providing documentation or additional context for the error.

  • title: A short, human-readable summary of the problem type. The title should be consistent across instances of the same problem.

  • status: The HTTP status code for the error.

  • detail: A human-readable explanation of the error.

  • instance: A URI reference that identifies the specific occurrence of the problem, providing a link for debugging or accessing more information.

Here is how you can apply RFC 9457 to your OpenAPI documentation:

paths:
  /user:
    post:
      summary: Create a new user
      responses:
        '400':
          description: Validation Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'


components:
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri-reference
          description: URI reference identifying the problem type.
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: HTTP status code for this error occurrence.
        detail:
          type: string
          description: Explanation specific to this occurrence of the problem.
        instance:
          type: string
          format: uri-reference
          description: URI reference identifying the specific occurrence of the problem.