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 thecontent-type
isapplication/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:
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 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 levelstatusCodes:- 404- 500get: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- 503operationId: getDrinksresponses:200:description: OKcontent:application/json:schema:type: arrayitems:$ref: "#/components/schemas/Drink"401:description: Unauthorizedcontent: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 forschema:$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 Errorcontent: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: getDrinksresponses:200:description: OKcontent:application/json:schema:type: arrayitems:$ref: "#/components/schemas/Drink"401:description: Unauthorizedcontent:application/json:schema:type: objectproperties:message:x-speakeasy-error-message: true # This will make the SDK use the value of the message property as the error messagetype: stringcode:type: integerrequired:- 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 thepaths
,path item
, oroperation
level. -
Set the
clientServerStatusCodesAsErrors
option tofalse
in yourgen.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.