Customize Error Handling

Speakeasy SDKs provide a default error-handling mechanism that will return an error object for any 4XX or 5XX response or a connection error while attempting to contact the API.

The error object returned will depend on the type of error and the documentation of status codes within the responses object of an operation in the OpenAPI document.

• Connection errors will either return a native connection error or a generic error with a message describing the error.
• Status code errors for documented status codes that fall within the 4XX or 5XX ranges will return error objects generated from the response object in the OpenAPI document, as long as content-type is application/json.
• Status code errors for undocumented status codes that fall within the 4XX or 5XX range will return SDK error objects containing the status code, the response body as a string, and the raw response object.

Overriding Default Error Handling Behavior

You can use the x-speakeasy-errors extension to override the default error-handling behavior of the SDKs.

The x-speakeasy-errors extension can be applied at the paths, path item, or operation level of the document. Deeper levels of the extension will either merge or override the behavior of the parent level.

The x-speakeasy-errors extension is an object with the following properties:

If the array of statusCodes contains any status codes that are not documented in the OpenAPI document, the SDK will return an SDK error object containing the status code, the response body as a string, and the raw response object. Otherwise, it will return an error object generated from the response object in the OpenAPI document, as long as content-type is application/json.

Example:

paths:
  x-speakeasy-errors:
    statusCodes: # Defines status codes to handle as errors for all operations
      - 4XX # Wildcard to handle all status codes in the 400-499 range
      - 5XX
  /drinks:
    x-speakeasy-errors:
      override: true # Forces this path and its operations to only handle 404 and 500 as errors, overriding the parent x-speakeasy-errors extension at the paths level
      statusCodes:
        - 404
        - 500
    get:
      x-speakeasy-errors:
        statusCodes: # As override is not set to true, this operation will handle 404, 401, 500, and 503 as errors, merging with the parent x-speakeasy-errors extension at the path item level
          - 401
          - 503
      operationId: getDrinks
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Drink'
        401:
          description: Unauthorized
          content:
            application/json: # As an application/json response is defined, the schema will generate a custom error object (for example `AuthError`) that will be returned and can be tested for
              schema:
                $ref: '#/components/schemas/AuthError'
        404:
          description: Not Found # As no application/json response is defined, the SDK will return a standard SDK error object.
        500:
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        503:
          description: Service Unavailable

Disabling Default Status Code Error Handling Behavior

If you don't want the SDK to handle 4XX or 5XX status codes as errors by default, you can do one of the following:

• Use the x-speakeasy-errors extension at the paths, path item, or operation level of the document to override the behavior.
• Set the clientServerStatusCodesAsErrors option to false in your gen.yaml file for the language you are generating the SDK for, and the SDK will return a response object for any documented status code. For example:

go:
    clientServerStatusCodesAsErrors: false