Customize Error Handling

Error handling varies across programming languages. Java, C#, Python, PHP, and others throw exceptions that are caught in special code blocks. Go methods, however, return error objects that must be explicitly checked by the programmer.

Speakeasy SDKs provide a default error-handling mechanism that returns an error object for connection errors and any 4XX or 5XX response.

The error object returned depends on the type of error and the status codes documented in the OpenAPI response object.

• Connection Errors: These throw either a native connection error or a generic error with a descriptive message.
• Documented Status Codes (4XX-5XX): If the content-type is application/json, errors are generated from the response object in the OpenAPI document.
• Undocumented Status Codes (4XX-5XX): These return SDK error objects containing the status code, 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 SDKs.

Applying the Speakeasy Errors Extension

Apply the x-speakeasy-errors extension at the paths, path item, or operation level. Deeper levels merge or override parent behavior.

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

If the statusCodes array contains undocumented status codes, the SDK returns an SDK error object with the status code, response body as a string, and the raw response object. Otherwise, if content-type is application/json, it returns an error object from the response object in the OpenAPI document.

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

Renaming Generated Error Classes

Refer to the Customizing Types documentation to rename generated error classes.

Configuring Error Message Location

You can use x-speakeasy-error-message to configure where the error message resides in the response object, ensuring the default printed message is returned by the API.

paths:
  /drinks:
    get:
      operationId: getDrinks
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Drink"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    x-speakeasy-error-message: true # This will make the SDK use the value of the message property as the error message
                    type: string
                  code:
                    type: integer
                required:
                  - message
                  - code

Disabling Default Status-Code Error-Handling Behavior

To prevent the SDK from handling 4XX or 5XX status codes as errors by default:

• Use the x-speakeasy-errors extension at the paths, path item, or operation level.

• Set the clientServerStatusCodesAsErrors option to false in your gen.yaml file for the SDK language:

  go:
    clientServerStatusCodesAsErrors: false

Handling the Default Error Response

The default response code is a catch-all for any status code not explicitly defined. By default, Speakeasy SDKs treat default responses as normal responses. To treat it as a specific error type, define the default response in the x-speakeasy-errors extension on any operation:

x-speakeasy-errors:
  statusCodes:
    - "default"

Enum Format Configuration in TypeScript SDKs

When handling errors in TypeScript SDKs, you may encounter enums in response objects. The enumFormat configuration option in the gen.yaml file allows you to configure how these enums are generated.

Using union types instead of traditional enums offers several benefits:

• Flexibility: Union types provide more flexibility when dealing with runtime values that might not perfectly match the enum definition, which is particularly useful in error responses.
• Code Completion: Literal types used in union types work seamlessly with the language server, ensuring that all IDEs provide autocompletion for available values.

typescript:
  enumFormat: union

This configuration is particularly useful for error handling when you prefer to work with union types instead of enum types, allowing you more flexibility with runtime values.