Customize responses

Response formats

When generating SDKs, response formats determine the structure of response types in supported languages. Three available response formats are available to choose from.

Configure the response format for a given target in the gen.yaml file:

The following sections will reference this specification:

responseFormat: flat

The flat response format is the simplest and most ergonomic option, as it avoids generating a wrapper type, giving SDK users direct access to the response value.

When responseFormat: flat is enabled, the generated SDK code will return the Payment type directly with no indirection:

To debug HTTP metadata, users can pass a custom client to the SDK instance.

responseFormat: envelope-http

The envelope-http format builds response types with a wrapper that holds the response value and associated HTTP metadata.

When envelope-http is enabled, the generated SDK code will produce the response types below:

Built-in HTTP metadata is included in both custom and built-in error types that are thrown or returned from the SDK.

Of the three response formats, envelope-http provides the most details about the underlying HTTP requests but adds a layer of indirection with a wrapper value.

Accessing HTTP headers with envelope-http

When using envelope-http, HTTP headers are accessible through the httpMeta.response.headers property, providing a cleaner structure than using rawResponse:

Headers in SDKs

Headers in SDKs are treated as metadata rather than structured response objects for several reasons:

• Headers are metadata, separate from the main response payload
• The dynamic nature of headers makes strict typing impractical
• This approach follows standard SDK behavior across the industry

While headers can be defined with types in OpenAPI, SDKs generally don’t expose them as typed properties. The envelope-http format provides a clear separation between HTTP metadata (including headers) and the main response payload.

responseFormat: envelope

The responseFormat: envelope format builds response types with a wrapper that holds the response value and minimal information about the underlying HTTP response.

Using envelope-http instead of envelope is recommended as it provides a more complete view of the HTTP request and response.

When responseFormat: envelope is enabled, the generated SDK code will produce the response types below: