Error conventions define a consistent approach for representing and handling errors in API responses. They ensure that clients receive predictable and structured error information that improves debugging and automation and enhances the overall user experience. You can specify how errors should be structured, what fields should be included, and how these schemas should be referenced in non-successful responses.

Define a canonical error schema

A canonical error schema serves as the single source of truth for error representation. It should include essential fields such as an error code, a message, and optional details for context.

The following example shows a recommended error schema:
ErrorResponse:
  title: ErrorResponse
  type: object
  required: [code, message]
  properties:
    code:
      type: string
      description: Machine readable error code
    message:
      type: string
      description: Human readable message
    details:
      type: object
      additionalProperties: true
      description: Optional structured context

Always reference the canonical error schema in all non-successful responses, such as 4xx and 5xx status codes. This approach ensures that generated tools and client applications can handle errors consistently.