Customize Error Handling
Speakeasy SDKs provide a default error-handling mechanism that will return an error object for any 4XX or 5XX response or a connection error while attempting to contact the API.
The error object returned will depend on the type of error and the documentation of status codes within the responses object of an operation in the OpenAPI document.
- Connection errors will either return a native connection error or a generic error with a message describing the error.
- Status code errors for documented status codes that fall within the 4XX or 5XX ranges will return error objects generated from the response object in the OpenAPI document, as long as
- Status code errors for undocumented status codes that fall within the 4XX or 5XX range will return SDK error objects containing the status code, the response body as a string, and the raw response object.
You can use the
x-speakeasy-errors extension to override the default error-handling behavior of the SDKs.
x-speakeasy-errors extension can be applied at the
path item, or
operation level of the document. Deeper levels of the extension will either merge or override the behavior of the parent level.
x-speakeasy-errors extension is an object with the following properties:
|If set to |
|An array of status codes that should be handled as errors. This will merge with any parent |
If the array of
statusCodes contains any status codes that are not documented in the OpenAPI document, the SDK will return an SDK error object containing the status code, the response body as a string, and the raw response object. Otherwise, it will return an error object generated from the response object in the OpenAPI document, as long as
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
If you don't want the SDK to handle
5XX status codes as errors by default, you can do one of the following:
- Use the
x-speakeasy-errorsextension at the
path item, or
operationlevel of the document to override the behavior.
- Set the
gen.yamlfile for the language you are generating the SDK for, and the SDK will return a response object for any documented status code. For example: