Module errors 

API error types and utilities translated from TypeScript errors.ts

Structs

AmazonError

Lower-level error that AWS can return

AmazonOutput

ApiErrorMessage

Assistant message structure for API errors

Enums

ApiErrorType

API error types for classification

SDKAssistantMessageError

SDK assistant message error types

Constants

API_ERROR_MESSAGE_PREFIX

Prefix for API error messages

API_TIMEOUT_ERROR_MESSAGE

API timeout error message

CCR_AUTH_ERROR_MESSAGE

CCR auth error message

CREDIT_BALANCE_TOO_LOW_ERROR_MESSAGE

Credit balance too low error message

CUSTOM_OFF_SWITCH_MESSAGE

Custom off switch message

INVALID_API_KEY_ERROR_MESSAGE

Invalid API key error message

INVALID_API_KEY_ERROR_MESSAGE_EXTERNAL

Invalid API key error message for external sources

NO_RESPONSE_REQUESTED

Constant for no response requested

OAUTH_ORG_NOT_ALLOWED_ERROR_MESSAGE

OAuth org not allowed error message

ORG_DISABLED_ERROR_MESSAGE_ENV_KEY

Organization disabled error message (env key)

ORG_DISABLED_ERROR_MESSAGE_ENV_KEY_WITH_OAUTH

Organization disabled error message (env key with OAuth)

PROMPT_TOO_LONG_ERROR_MESSAGE

Prompt too long error message

REPEATED_529_ERROR_MESSAGE

Repeated 529 error message

TOKEN_REVOKED_ERROR_MESSAGE

Token revoked error message

Functions

categorize_retryable_api_error

Categorize retryable API errors

classify_api_error

Classifies an API error into a specific error type for analytics tracking. Returns a standardized error type string suitable for tagging.

create_assistant_api_error_message

Create an assistant API error message

create_assistant_api_error_message_with_options

Create an assistant API error message with optional parameters

error_to_api_message

Map a raw error message to a rich ApiErrorMessage with structured content, error type, and optional error_details. Mirrors the TypeScript getAssistantMessageFromError() function.

extract_unknown_error_format

Given a response that doesn’t look quite right, see if it contains any known error types

get_error_message_if_refusal

Get error message if refusal

get_image_too_large_error_message

Get image too large error message

get_oauth_org_not_allowed_error_message

Get OAuth org not allowed error message

get_pdf_invalid_error_message

Get PDF invalid error message

get_pdf_password_protected_error_message

Get PDF password protected error message

get_pdf_too_large_error_message

Get PDF too large error message based on session type

get_prompt_too_long_token_gap

Returns how many tokens over the limit a prompt-too-long error reports, or undefined if the message isn’t PTL or its error_details are unparseable.

get_request_too_large_error_message

Get request too large error message

get_token_revoked_error_message

Get token revoked error message

is_ccr_mode

Check if we’re in CCR (Claude Code Remote) mode. In CCR mode, auth is handled via JWTs provided by the infrastructure, not via /login. Transient auth errors should suggest retrying, not logging in. Note: This is a placeholder - actual implementation would check environment

is_media_size_error

Is this raw API error text a media-size rejection? Patterns MUST stay in sync with the getAssistantMessageFromError branches that populate error_details (~L523 PDF, ~L560 image, ~L573 many-image) and the classifyAPIError branches (~L929-946).

is_media_size_error_message

Message-level predicate: is this assistant message a media-size rejection?

is_prompt_too_long_message

Check if a message is a prompt too long error

is_valid_api_message

Type guard to check if a value is a valid API message response

parse_prompt_too_long_token_counts

Parse actual/limit token counts from a raw prompt-too-long API error message like “prompt is too long: 137500 tokens > 135000 maximum”. The raw string may be wrapped in SDK prefixes or JSON envelopes, or have different casing (Vertex), so this is intentionally lenient.

sanitize_html_error

Sanitize an HTTP error body: if it looks like an HTML error page (e.g., 502/503 from a reverse proxy), extract the page title instead of dumping the full HTML into the error message.

starts_with_api_error_prefix

Check if text starts with API error prefix