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/throws an error object for connection errors and any 4XX or 5XX response.

The error object returned/thrown depends on the type of error and the status codes documented in the OpenAPI response object. The error object returned/thrown will depend on the type of error and how status codes are documented in the response object of the operation in the OpenAPI document.

Connection Errors: Either a native connection error or a generic error with a descriptive message.
Documented Status Codes (4XX-5XX): If content-type is application/json, errors are generated from the response object in the OpenAPI document.
Undocumented Status Codes (4XX-5XX): Returns/throws SDK error objects containing the status code, response body as a string, and the raw response object.

Overriding Default Error-Handling Behavior

Use the x-speakeasy-errors extension to override the default error-handling behavior of SDKs.

Applying the `x-speakeasy-errors` Extension

Apply the 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:

Property	Type	Description
`override`	`boolean`	If `true`, the statusCodes list overrides any parent `x-speakeasy-errors` extension for this object and its children. Defaults to `false`.
`statusCodes`	`[string]`	An array of status codes to handle as errors. Merges with any parent `x-speakeasy-errors` extension unless override is `true`. Each status code must be in quotation marks (e.g., `"503"`) for JSON and YAML compatibility. Wildcards (e.g., `5XX`) are supported.

If the statusCodes array contains undocumented status codes, the SDK returns/throws an SDK error object with the status code, response body as a string, and the raw response object. Otherwise, it returns/throws an error object from the response object in the OpenAPI document if 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

Renaming generated error classes

Refer to Customizing Types documentation to rename generated error classes.

Configuring Error Message Location

With x-speakeasy-error-message, configure where the error message resides in the response object, ensuring the default printed message is the one 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 auto-completion 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 more flexibility with runtime values.