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:

PropertyTypeDescription
overridebooleanIf 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 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

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

python:
defaultErrorName: CustomDefaultException

To rename other generated error classes, please 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.