Errors & retries

Every SDK raises the same Bedrock-named exceptions, so your existing error-handling paths — including catch-and-backoff logic keyed on ThrottlingException — port over unchanged. Every server-derived error carries message, statusCode, errorCode, requestId (quote it to support), retryAfterSeconds, and the raw response body.

Exception	Retried automatically	Typical cause
`ValidationException`	no	Malformed request (HTTP 400)
`AccessDeniedException`	no	Bad or missing key; model not allowed (401/403)
`ResourceNotFoundException`	no	Unknown model (404)
`ServiceQuotaExceededException`	no	Budget / usage cap exhausted (402, or 429 with `BUDGET_EXCEEDED`)
`ThrottlingException`	yes	Rate limited (429) — honors `Retry-After`
`ModelTimeoutException`	yes	Model timeout (408)
`ModelErrorException`	no	Model-level failure
`ModelStreamErrorException`	no	Stream interrupted after the first byte
`ServiceUnavailableException`	yes	Upstream unavailable (502/503/504)
`InternalServerException`	yes	Gateway error (500)
`MissingApiKeyError`	—	No key resolved; fails before any network call
`SdkError`	network only	Connection / decode failure

from audacity.exceptions import SdkError

try:
    response = client.converse(modelId="gpt-5.4-mini", messages=[…])
except client.exceptions.ThrottlingException as e:
    print(f"Rate limited: {e.message}, retry after {e.retry_after_seconds}s")
except client.exceptions.AccessDeniedException as e:
    print(f"Auth error [{e.status_code}]: {e.message}")
except client.exceptions.ServiceQuotaExceededException as e:
    print(f"Budget exhausted: {e.message}")
except SdkError as e:
    print(f"Network/decode error: {e.message}")

import {
  AccessDeniedException,
  ThrottlingException,
  MissingApiKeyError,
  AudacityError,
} from "@audacity/sdk";

try {
  const res = await client.send(new ConverseCommand({ /* … */ }));
} catch (err) {
  if (err instanceof MissingApiKeyError) {
    console.error("No API key configured");
  } else if (err instanceof AccessDeniedException) {
    console.error("Auth failed:", err.message, "requestId:", err.requestId);
  } else if (err instanceof ThrottlingException) {
    console.error("Rate limited. Retry after:", err.retryAfterSeconds, "s");
  } else if (err instanceof AudacityError) {
    // All SDK errors are instances of AudacityError
    console.error(err.name, err.statusCode, err.errorCode);
  }
}

_, err := client.Converse(ctx, input)
switch {
case err == nil:
    // success
case errors.Is(err, &types.MissingAPIKeyError{}):
    log.Fatal("set AUDACITY_API_KEY")
default:
    var throttle *types.ThrottlingException
    var quota *types.ServiceQuotaExceededException
    var accessDenied *types.AccessDeniedException

    switch {
    case errors.As(err, &throttle):
        fmt.Printf("rate limited (retry-after=%v)\n", throttle.RetryAfterSeconds)
    case errors.As(err, &quota):
        fmt.Println("budget exhausted — will not retry")
    case errors.As(err, &accessDenied):
        fmt.Println("check your API key")
    default:
        log.Fatal(err)
    }
}

try {
    ConverseResponse resp = client.converse(request -> request
        .modelId("gpt-5.4-mini")
        .messages(Message.builder()
            .role(ConversationRole.USER)
            .content(ContentBlock.fromText("Hi"))
            .build()));
} catch (ThrottlingException e) {
    System.err.printf("Rate limited. Retry-After: %s s%n", e.retryAfterSeconds());
} catch (AccessDeniedException e) {
    System.err.println("Auth failed: " + e.getMessage());
} catch (ServiceQuotaExceededException e) {
    System.err.println("Budget or quota exceeded — not retried");
} catch (AudacityException e) {
    System.err.printf("SDK error [%d] %s%n", e.statusCode(), e.getMessage());
}

use audacity_sdk::Error;

match client.converse().model_id("m").messages(msg).send().await {
    Ok(resp) => { /* use resp */ }
    Err(Error::Throttling(d)) => {
        eprintln!("Rate limited (retry after {:?}s): {}", d.retry_after_seconds, d.message);
    }
    Err(Error::AccessDenied(d)) => {
        eprintln!("Access denied [{}]: {}", d.error_code.unwrap_or_default(), d.message);
    }
    Err(Error::MissingApiKey) => {
        eprintln!("Set AUDACITY_API_KEY");
    }
    Err(e) => eprintln!("Other error: {e}"),
}

Retry policy (Bedrock standard-mode analog)

Attempts = maxRetries + 1; the default is 2 retries (3 total attempts).
Retried: network errors, HTTP 429, 500, 502, 503, 504, and 408 — with full-jitter exponential backoff capped at 20 s, honoring any Retry-After header.
Never retried: auth failures, validation errors, unknown models, and budget exhaustion (BUDGET_EXCEEDED) — spending errors must never silently retry.
Streaming: retries apply only until response headers arrive. Once the first byte of the stream is consumed, a drop surfaces as ModelStreamErrorException — a partial generation is never silently replayed.

Reference

Endpoints

Retry policy (Bedrock standard-mode analog)

​Retry policy (Bedrock standard-mode analog)

Retry policy (Bedrock standard-mode analog)