Principle:Togethercomputer Together python API Error Handling

Attribute	Value
Principle Name	API_Error_Handling
Overview	Pattern for handling typed exceptions raised by the Together AI API client.
Domain	NLP, API_Client, Inference
Repository	togethercomputer/together-python
Last Updated	2026-02-15 16:00 GMT

Description

API error handling provides a structured exception hierarchy that maps HTTP status codes and client-side failures to typed Python exceptions. This enables programmatic error handling with specific catch clauses for authentication failures, rate limiting, invalid requests, timeouts, and service availability issues.

The Together SDK defines a base TogetherException class from which all specific exceptions inherit. Each exception carries contextual information:

message -- A human-readable error description, optionally including the HTTP status code prefix.
http_status -- The HTTP status code that triggered the error (when applicable).
headers -- Response headers from the API (useful for debugging and rate limit information).
request_id -- A unique identifier for the failed request (useful for support inquiries).

Exception Categories

The hierarchy organizes errors into distinct semantic categories:

Authentication errors (AuthenticationError) -- Raised when the API key is missing, invalid, or expired. Maps to HTTP 401.
Rate limiting (RateLimitError) -- Raised when the API rate limit has been exceeded. Maps to HTTP 429.
Invalid requests (InvalidRequestError) -- Raised for malformed requests, invalid parameters, or unsupported configurations. Maps to HTTP 400/422.
Server errors (APIError) -- Raised for internal server errors. Maps to HTTP 500.
Service unavailability (ServiceUnavailableError) -- Raised when the API service is temporarily unavailable. Maps to HTTP 503.
Transport errors (Timeout, APIConnectionError) -- Raised for network-level failures that prevent the request from completing.
Response parsing errors (ResponseError, JSONError) -- Raised when the API response cannot be parsed or is in an unexpected format.
Resource errors (InstanceError, FileTypeError, DownloadError, AttributeError) -- Raised for domain-specific failures related to model instances, file operations, and attribute validation.

Usage

Use API error handling when making any API call to handle failures gracefully. Wrap API calls in try/except blocks catching specific exception types.

When to use:

Around every API call in production code to prevent unhandled crashes
When implementing retry logic for transient errors (rate limits, timeouts, 503s)
When providing user-facing error messages that differ based on the failure type
When logging errors with appropriate severity levels
When building fault-tolerant pipelines that should continue on non-fatal errors

Recommended error handling patterns:

Catch specific exceptions before catching the base TogetherException.
For RateLimitError, implement exponential backoff retry logic.
For Timeout and APIConnectionError, retry with the same request.
For AuthenticationError, fail fast -- retrying will not help.
For InvalidRequestError, fail fast -- the request parameters need to be corrected.
For ServiceUnavailableError and APIError, retry after a delay.

Theoretical Basis

Exception hierarchies map protocol-level errors (HTTP 401, 429, 500, etc.) to semantic error types that applications can handle distinctly. This approach has several advantages over generic exception handling:

Specificity -- Different error types require different recovery strategies. A rate limit error should trigger a backoff, while an authentication error should halt the program.
Composability -- Catching the base TogetherException handles all API errors uniformly when specific handling is not needed.
Debuggability -- Structured error properties (http_status, request_id, headers) provide the context needed for diagnosis without parsing error message strings.
Idiomatic Python -- Python's exception hierarchy model (e.g., OSError subtypes) establishes the convention of using exception class identity for programmatic error discrimination.

The SDK also supports structured error responses from the API via the TogetherErrorResponse Pydantic model, which is automatically serialized into the exception message when present.

Knowledge Sources

Source	Type	URI
Together AI Error Codes	Doc	Together AI Error Codes
Together AI Rate Limits	Doc	Together AI Rate Limits

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment