Customize Error Handling

Error handling differs across programming languages. Java, C#, Python, PHP and others throw exceptions that are caught in special code blocks. Go methods instead return error objects that are checked explicitly by the programmer.

Speakeasy SDKs provide a default error-handling mechanism that will return/throw an error object if there is a connection error while attempting to connect to the API and for any 4XX or 5XX response.

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 will either return/throw a native connection error or a generic error with a message describing the error.
If status codes are documented and content-type is application/json, status-code errors in the 4XX to 5XX range will return/throw error objects generated from the response object in the OpenAPI document.
If status codes are not documented, status-code errors in the 4XX to 5XX range will return/throw SDK error objects containing the status code, the 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.

Apply the x-speakeasy-errors extension at the paths, path item, or operation level of the document. Deeper levels of the extension will either merge or override the behavior of the parent level.

The x-speakeasy-errors extension is an object with the following properties:

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

If the array of statusCodes contains any status codes that are not documented in the OpenAPI document, the SDK will return/throw an SDK error object containing the status code, the response body as a string, and the raw response object. Otherwise, it will return/throw an error object generated from the response object in the OpenAPI document, as long as 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

You can rename the generated error classes by referring to the Customizing Types docs.

Configuring where the error message lives

With x-speakeasy-error-message you can configure where the error message lives in the response object. This allows the message printed by default by the error is the message 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

If you don't want the SDK to handle 4XX or 5XX status codes as errors by default, you can do one of the following:

Use the x-speakeasy-errors extension at the paths, path item, or operation level of the document to override the behavior.
Set the clientServerStatusCodesAsErrors option to false in your gen.yaml file for the language you are generating the SDK for, and the SDK will return a response object for any documented status code instead of returning/throwing errors. For example:


go:
  clientServerStatusCodesAsErrors: false

Handling the `default` error response

Often OpenAPI documents will include default as a response code. The default response is not a status code, but a catch-all for any status code that is not explicitly defined. By default, Speakeasy SDKs will treat any default response as a normal response. To treat it as a specific error type make sure to define the default response in the x-speakeasy-errors extension on any operation in the OpenAPI document.


x-speakeasy-errors:
  statusCodes:
    - "default"