Error handling

The backend SDKs group errors into a small typed hierarchy so you can write narrow catch blocks and access structured fields directly, without parsing response bodies yourself.

Exception classes

StreamRateLimitException extends StreamApiException, so a catch (StreamApiException ...) block matches 429s too. Catch the rate-limit subclass first if you want different handling.

Class names per SDK

The hierarchy is the same across SDKs. Class names follow each language's idiom.

In Go, branch on the sentinel with errors.Is(err, getstream.ErrApiResponse) and extract fields by unwrapping to *StreamError via errors.As.

Fields on the API exception

When the server returns a 4xx or 5xx with the standard error envelope, the API exception carries every documented field. Use these directly instead of re-parsing the response body.

Catching API errors

from getstream.exceptions import StreamApiException, StreamRateLimitException

try:
    client.send_message(...)
except StreamRateLimitException as e:
    # 429; e.retry_after is a timedelta or None
    if e.retry_after:
        time.sleep(e.retry_after.total_seconds())
except StreamApiException as e:
    if e.status_code == 422:
        for field, msg in e.exception_fields.items():
            print(f"{field}: {msg}")
    if e.unrecoverable:
        raise

begin
  client.send_message(...)
rescue GetStreamRuby::RateLimitError => e
  sleep(e.retry_after || 1)
rescue GetStreamRuby::ApiError => e
  if e.status_code == 422
    e.exception_fields.each { |field, msg| warn "#{field}: #{msg}" }
  end
  raise if e.unrecoverable
end

use GetStream\Exceptions\StreamApiException;
use GetStream\Exceptions\StreamRateLimitException;

try {
    $client->sendMessage(...);
} catch (StreamRateLimitException $e) {
    // $e->getRetryAfter() is ?int (seconds)
    sleep($e->getRetryAfter() ?? 1);
} catch (StreamApiException $e) {
    if ($e->getStatusCode() === 422) {
        foreach ($e->getExceptionFields() as $field => $msg) {
            error_log("$field: $msg");
        }
    }
    if ($e->isUnrecoverable()) {
        throw $e;
    }
}

import (
    "errors"
    "github.com/GetStream/getstream-go/v4"
)

_, err := client.SendMessage(ctx, ...)
var streamErr *getstream.StreamError
if errors.As(err, &streamErr) {
    if errors.Is(err, getstream.ErrRateLimited) {
        time.Sleep(streamErr.RetryAfter)
    } else if errors.Is(err, getstream.ErrApiResponse) {
        if streamErr.StatusCode == 422 {
            for field, msg := range streamErr.ExceptionFields {
                fmt.Printf("%s: %s\n", field, msg)
            }
        }
        if streamErr.Unrecoverable {
            return err
        }
    }
}

using GetStream;

try
{
    await client.SendMessageAsync(...);
}
catch (GetStreamRateLimitException ex)
{
    // 429; ex.RetryAfter is a TimeSpan?
    await Task.Delay(ex.RetryAfter ?? TimeSpan.FromSeconds(1));
}
catch (GetStreamApiException ex) when (ex.StatusCode == 422)
{
    foreach (var (field, msg) in ex.ExceptionFields)
    {
        Console.WriteLine($"{field}: {msg}");
    }
    if (ex.Unrecoverable)
    {
        throw;
    }
}

import io.getstream.exceptions.StreamApiException;
import io.getstream.exceptions.StreamRateLimitException;

try {
    client.sendMessage(...);
} catch (StreamRateLimitException e) {
    if (e.getRetryAfter() != null) {
        Thread.sleep(e.getRetryAfter().toMillis());
    }
} catch (StreamApiException e) {
    if (e.getStatusCode() == 422) {
        e.getExceptionFields().forEach((field, msg) -> System.out.println(field + ": " + msg));
    }
    if (e.isUnrecoverable()) {
        throw e;
    }
}

Transport errors

Transport errors are failures that happen before the server can respond: connection refused or reset, request timeout, DNS lookup failure, TLS handshake failure. The SDK catches these at the HTTP-client boundary and re-emits them as a typed transport exception with a categorized errorType. The original error is preserved on the cause chain.

This means callers do not have to catch httpx.RequestError, HttpRequestException, Faraday::Error, GuzzleException, IOException, or net.Error separately. One catch block covers all transport-layer failures.

The errorType enum

The transport exception always exposes the underlying error via the language-native cause-chain accessor.

Catching transport errors

from getstream.exceptions import StreamTransportException

try:
    client.do_something()
except StreamTransportException as e:
    # e.error_type is one of connection_reset / timeout / dns_failure / tls_handshake_failed / unknown
    # e.__cause__ is the underlying httpx exception
    if e.error_type == "timeout":
        # back off and try again later
        ...

begin
  client.do_something
rescue GetStreamRuby::TransportError => e
  # e.error_type is one of connection_reset / timeout / dns_failure / tls_handshake_failed / unknown
  # e.cause is the underlying Faraday error
  if e.error_type == 'timeout'
    # back off and try again later
  end
end

use GetStream\Exceptions\StreamTransportException;

try {
    $client->doSomething();
} catch (StreamTransportException $e) {
    // $e->getErrorType() is one of connection_reset / timeout / dns_failure / tls_handshake_failed / unknown
    // $e->getPrevious() is the underlying Guzzle exception
    if ($e->getErrorType() === 'timeout') {
        // back off and try again later
    }
}

import (
    "errors"
    "github.com/GetStream/getstream-go/v4"
)

_, err := client.DoSomething(ctx, ...)
if errors.Is(err, getstream.ErrTransport) {
    var streamErr *getstream.StreamError
    errors.As(err, &streamErr)
    // streamErr.ErrorType is one of connection_reset / timeout / dns_failure / tls_handshake_failed / unknown
    // errors.Unwrap(err) returns the underlying transport error
    if streamErr.ErrorType == "timeout" {
        // back off and try again later
    }
}

using GetStream;

try
{
    await client.DoSomethingAsync();
}
catch (GetStreamTransportException ex)
{
    // ex.ErrorType is one of connection_reset / timeout / dns_failure / tls_handshake_failed / unknown
    // ex.InnerException is the underlying HttpRequestException / TaskCanceledException / etc.
    if (ex.ErrorType == "timeout")
    {
        // back off and try again later
    }
}

import io.getstream.exceptions.StreamTransportException;

try {
    client.doSomething();
} catch (StreamTransportException e) {
    // e.getErrorType() is one of connection_reset / timeout / dns_failure / tls_handshake_failed / unknown
    // e.getCause() is the underlying IOException
    if ("timeout".equals(e.getErrorType())) {
        // back off and try again later
    }
}

Distinguishing transport errors from API errors

Transport errors happen when no HTTP response was received. API errors happen when the server responded with a 4xx or 5xx. Catch them separately if you want to react differently:

from getstream.exceptions import StreamApiException, StreamTransportException

try:
    client.do_something()
except StreamApiException as e:
    # server responded with a 4xx/5xx
    handle_api_error(e)
except StreamTransportException as e:
    # network or transport-layer failure
    handle_transport_error(e)

_, err := client.DoSomething(ctx, ...)
if errors.Is(err, getstream.ErrApiResponse) {
    // server responded with a 4xx/5xx
} else if errors.Is(err, getstream.ErrTransport) {
    // network or transport-layer failure
}

Both transport and API exceptions inherit from the SDK's base exception. Catch that base type if you want to handle all SDK-emitted errors uniformly.

Cause-chain preservation

Every wrapping point preserves the underlying cause via the language-native mechanism. You can always recover the original exception when you need it for diagnostics or instrumentation.

Migration notes

Python: deprecated StreamAPIException alias

getstream.base.StreamAPIException (capital API) is preserved as a deprecated alias for StreamApiException. Existing except StreamAPIException blocks and isinstance(exc, StreamAPIException) checks keep working, with a one-time DeprecationWarning on import. Switch to the new spelling at your convenience. The alias is slated for removal in the following minor release.

Ruby: deprecated Stream::APIError alias

GetStreamRuby::APIError (capital API) is preserved as a deprecated alias for GetStreamRuby::ApiError. First access emits a one-time Kernel.warn. Slated for removal in v9.0.

PHP: getCode() semantics

StreamApiException::getCode() continues to return the HTTP status code, the pre-existing behavior inherited from \Exception::getCode(). Stream's canonical numeric error code from the response envelope is now exposed via the new getApiErrorCode(): int. Existing callers branching on $e->getCode() === 429 continue to work. Switch to getApiErrorCode() if you need the envelope code instead of the HTTP status.

.NET: per-status subclasses removed

The previously-published GetStreamAuthenticationException, GetStreamValidationException, and GetStreamFeedException are removed. They were never thrown by the SDK, so no existing catch block was reached. If you have defensive catch blocks for those types, replace them with status-code filters on GetStreamApiException.

// before (never matched)
catch (GetStreamAuthenticationException ex) { ... }

// after
catch (GetStreamApiException ex) when (ex.StatusCode is 401 or 403) { ... }