Speakeasy Logo
Skip to Content
DocumentationCustomizeResponses & Error HandlingError Handling

Customize Error Handling

Below is a structured guide on how to configure and customize error handling in Speakeasy-generated SDKs.

Default Error Handling (no configuration)

By default, Speakeasy SDKs handle errors as follows:

  1. Validation Errors: If the server response doesn’t match the SDK’s expected data schema, validation errors will be raised.
  2. 4XX and 5XX Status Codes: Responses with these status codes are treated as errors.
  3. Connection Errors: If the SDK fails to connect to the server (DNS, timeouts, TLS errors), it raises a connection-related error/exception.

Example OpenAPI file

TypeScript SDK Default Error Handling

To improve the DX for the end user of the SDK, it is recommended to have named error classes for certain types of errors eg UnauthorizedError, NotFoundError, etc. It is also common for APIs to return structured JSON errors for 4XX responses. Here is an example of how to configure this in an OpenAPI document:

Note, defining 5XX responses is generally not recommended as the server is not always in control of the response. If a JSON schema is specified for a 5XX response and the response doesn’t match the schema, the SDK will raise a SDKValidationError.

Note the use of x-speakeasy-error-message: true to configure the error message to be used by the SDK, which will be propagated to err.message in the SDK.

TypeScript SDK Default Error Handling

Advanced Configuration

Renaming Generated Error Classes

Any unhandled API Error will raise a exception of the default SDKError/APIError/APIException class depending on the SDK language. To change the name of the default error class, edit the defaultErrorName parameter in the gen.yaml file for the corresponding SDK language:

To rename other generated error classes, please refer to the Customizing Types documentation to rename generated error classes.

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 non-error responses. To treat it as a specific error type, define the default response in the x-speakeasy-errors extension on any operation:

Disabling Default Error Handling

In certain cases, you may want to disable the default error handling behavior of SDKs. For example, you may not want to throw an error for a 404 status code.

The x-speakeasy-errors extension can be used to override the default error-handling behavior of SDKs.

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:

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

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:

Another way to disable default error handling is to set the clientServerStatusCodesAsErrors option to false in the gen.yaml file for the SDK language:

Last updated on