Skip to main content

Enhanced Error Handling in Code Samples Across SDKs

· 5 min read

We have improved error handling in PHP, TypeScript, Java, .NET, and Go code samples to make it clearer, more consistent, and easier to handle typed errors, while still exposing response metadata like status codes and headers.

What's New​

We have improved error handling in code samples across our SDKs and Developer Portal, making success and failure paths clearer, more consistent, and idiomatic for each language. Key enhancements include:

  • Prominent exposure of response status codes and headers.
  • Typed error handling where supported, enabling precise, branchable error flows.
  • Concise and idiomatic success and error handling aligned with each language’s best practices.

Below are examples using the getTransactions API, that may return CustomAlphaException or CustomBetaException for error status codes. This is how the SDKs and the Developer Portal now showcase error handling in code samples, enhancing the end-user experience when consuming the SDKs.

PHP​

PHP code samples now show typed error handling for each error type defined in your OpenAPI specification, providing more granular control.

note

The following new behavior is only available when Map Error Types in Complete Response for PHP setting is enabled.

$apiResponse = $client->getPaymentsApi()->getTransactions();

// Extracting response status code
var_dump($apiResponse->getStatusCode());
// Extracting response headers
var_dump($apiResponse->getHeaders());

if ($apiResponse->isSuccess()) {
    $data = $apiResponse->getResult();
    echo "ResponseType: ";
    var_dump($data);
} else {
    $error = $apiResponse->getResult();
    if ($error instanceof CustomAlphaException) {
        echo "CustomAlphaException: $error";
    } elseif ($error instanceof CustomBetaException) {
        echo "CustomBetaException: $error";
    }
}

TypeScript​

Previously, in TypeScript code samples, ApiError handling only logged status, headers, and the raw body. The new approach preserves error metadata logging and adds typed error branches that expose a structured result for targeted handling.

try {
  const response = await paymentsApi.getTransactions();
  // Extracting fully parsed response body.
  console.log(response.result);
  // Extracting response status code.
  console.log(response.statusCode);
  // Extracting response headers.
  console.log(response.headers);
  // Extracting response body of type `string | Stream`
  console.log(response.body);
} catch (error) {
  if (error instanceof ApiError) {
    // Extracting response error status code.
    console.log(error.statusCode);
    // Extracting response error headers.
    console.log(error.headers);
    // Extracting response error body of type `string | Stream`.
    console.log(error.body);
    if (error instanceof CustomAlphaError) {
      console.log(error.result);
    } else if (error instanceof CustomBetaError) {
      console.log(error.result);
    }
  }
}

Go​

In Go code samples, the old code terminated on error using log.Fatalln. The new version switches between error types defined in the openapi specification to handle known cases explicitly, with a safe fallback, while keeping the success path unchanged.

ctx := context.Background()
apiResponse, err := paymentsApi.GetTransactions(ctx)
if err != nil {
    switch typedErr := err.(type) {
    case *errors.CustomAlpha:
        log.Fatalln("CustomAlphaException: ", typedErr)
    case *errors.CustomBeta:
        log.Fatalln("CustomBetaException: ", typedErr)
    default:
        log.Fatalln(err)
    }
} else {
    // Printing the result and response
    fmt.Println(apiResponse.Data)
    fmt.Println(apiResponse.Response.StatusCode)
}

Java​

In Java code samples, the old exceptionally handler printed stack traces generically. The new sample inspects exception.getCause() and branches to typed exceptions to enable focused recovery and messaging, with a generic fallback.

paymentsApi.getTransactions().thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    // TODO failure callback handler
    Throwable cause = exception.getCause();

    if (cause instanceof CustomAlphaException) {
        CustomAlphaException e = (CustomAlphaException) cause;
        e.printStackTrace();
    } else if (cause instanceof CustomBetaException) {
        CustomBetaException e = (CustomBetaException) cause;
        e.printStackTrace();
    } else {
        // fallback for unexpected errors
        exception.printStackTrace();
    }

    return null;
});

.NET​

Previously, .NET code samples used a single ApiException catch that printed the message. The new sample adds type checks for each error type defined in your OpenAPI specification to enable targeted handling blocks while retaining message logging.

try
{
    List<Transaction> result = await paymentsApi.GetTransactions();
}
catch (ApiException e)
{
    Console.WriteLine(e.Message);
    if (e is CustomAlphaException)
    {
        // TODO: Handle CustomAlphaException exception here
    }
    if (e is CustomBetaException)
    {
        // TODO: Handle CustomBetaException exception here
    }
}