Implementation:Togethercomputer Together python Together Exception Hierarchy

Attribute	Value
Implementation Name	Together_Exception_Hierarchy
Overview	Fourteen exception classes forming a typed error hierarchy for HTTP status codes and client-side failures.
Source File	src/together/error.py
Lines	L11-194
Domain	NLP, API_Client, Inference
Repository	togethercomputer/together-python
Last Updated	2026-02-15 16:00 GMT

Code Reference

Base Exception: TogetherException (L11-49)

class TogetherException(Exception):
    def __init__(
        self,
        message: (
            TogetherErrorResponse | Exception | str | RequestException | None
        ) = None,
        headers: str | Dict[Any, Any] | None = None,
        request_id: str | None = None,
        http_status: int | None = None,
    ) -> None:
        if isinstance(message, TogetherErrorResponse):
            self.api_response = message

        _message = (
            json.dumps(message.model_dump(exclude_none=True))
            if isinstance(message, TogetherErrorResponse)
            else message
        )
        if http_status is not None:
            self._message = f"Error code: {http_status} - {_message}"
        else:
            self._message = str(_message)

        super().__init__(self._message)

        self.http_status = http_status
        self.headers = headers or {}
        self.request_id = request_id

Full Exception Hierarchy

All subclasses inherit from TogetherException and accept the same message parameter plus **kwargs that are forwarded to the base class.

class AuthenticationError(TogetherException): ...    # HTTP 401
class RateLimitError(TogetherException): ...         # HTTP 429
class InvalidRequestError(TogetherException): ...    # HTTP 400/422
class APIError(TogetherException): ...               # HTTP 500
class ServiceUnavailableError(TogetherException): ...# HTTP 503
class Timeout(TogetherException): ...                # Client-side timeout
class APIConnectionError(TogetherException): ...     # Network connection failure
class ResponseError(TogetherException): ...          # Unexpected response format
class JSONError(TogetherException): ...              # JSON parsing failure
class InstanceError(TogetherException): ...          # No running model instances
class FileTypeError(TogetherException): ...          # Invalid file type
class DownloadError(TogetherException): ...          # File download failure
class AttributeError(TogetherException): ...         # Attribute validation failure

InstanceError (L85-95) -- Special Constructor

class InstanceError(TogetherException):
    def __init__(self, model: str | None = "model", **kwargs: Any) -> None:
        super().__init__(**kwargs)
        self.message = f"""No running instances for {model}.
                You can start an instance with one of the following methods:
                  1. navigating to the Together Playground at api.together.ai
                  2. starting one in python using together.Models.start(model_name)
                  3. `$ together models start <MODEL_NAME>` at the command line.
                See `together.Models.list()` in python or `$ together models list` in command line
                to get an updated list of valid model names.
                """

Import

from together.error import (
    TogetherException,
    AuthenticationError,
    RateLimitError,
    InvalidRequestError,
    APIError,
    ServiceUnavailableError,
    Timeout,
    APIConnectionError,
    ResponseError,
    JSONError,
    InstanceError,
    FileTypeError,
    DownloadError,
    AttributeError,
)

I/O Contract

Base Exception Constructor Parameters

Parameter	Type	Default	Description
message	Exception | str | RequestException | None	None	Error message or structured error response from the API.
headers	Dict[Any, Any] | None	None	HTTP response headers (defaults to empty dict).
request_id	None	None	Unique identifier for the failed request.
http_status	None	None	HTTP status code that triggered the error.

Exception Properties

Property	Type	Description
._message	str	Formatted error message. Prefixed with "Error code: {status} - " when http_status is set.
.http_status	None	HTTP status code (e.g., 401, 429, 500).
.headers	Dict | {}	Response headers.
.request_id	None	Request identifier for debugging.
.api_response	TogetherErrorResponse	Structured API error response (only set when message is a TogetherErrorResponse).

Exception Class to HTTP Status Mapping

Exception Class	HTTP Status	Trigger Condition
AuthenticationError	401	Missing, invalid, or expired API key.
RateLimitError	429	API rate limit exceeded.
InvalidRequestError	400, 422	Malformed request or invalid parameters.
APIError	500	Internal server error.
ServiceUnavailableError	503	Service temporarily unavailable.
Timeout	N/A	Request exceeded configured timeout.
APIConnectionError	N/A	Network connection failure.
ResponseError	N/A	Unexpected response format.
JSONError	N/A	Failed to parse JSON response.
InstanceError	N/A	No running model instances available.
FileTypeError	N/A	Invalid file type for the operation.
DownloadError	N/A	File download failed.
AttributeError	N/A	Attribute validation failure.

Usage Examples

Basic Error Handling

from together import Together
from together.error import (
    TogetherException,
    AuthenticationError,
    RateLimitError,
    InvalidRequestError,
    Timeout,
)

client = Together()

try:
    response = client.chat.completions.create(
        model="meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
    print(f"HTTP Status: {e.http_status}")  # 401
except RateLimitError as e:
    print(f"Rate limited: {e}")
    print(f"Headers: {e.headers}")  # May contain retry-after info
except InvalidRequestError as e:
    print(f"Invalid request: {e}")
    print(f"Request ID: {e.request_id}")
except Timeout as e:
    print(f"Request timed out: {e}")
except TogetherException as e:
    print(f"API error: {e}")
    print(f"HTTP Status: {e.http_status}")

Retry with Exponential Backoff

import time
from together import Together
from together.error import RateLimitError, Timeout, ServiceUnavailableError

client = Together()

def chat_with_retry(messages, model, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
            )
        except (RateLimitError, Timeout, ServiceUnavailableError) as e:
            if attempt == max_retries - 1:
                raise
            delay = 2 ** attempt  # 1s, 2s, 4s
            print(f"Attempt {attempt + 1} failed ({type(e).__name__}), retrying in {delay}s...")
            time.sleep(delay)

response = chat_with_retry(
    messages=[{"role": "user", "content": "Hello!"}],
    model="meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
)

Comprehensive Error Handling for Production

from together import Together
from together.error import (
    TogetherException,
    AuthenticationError,
    RateLimitError,
    InvalidRequestError,
    APIError,
    ServiceUnavailableError,
    Timeout,
    APIConnectionError,
)

client = Together()

try:
    response = client.chat.completions.create(
        model="meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response.choices[0].message.content)

except AuthenticationError:
    # Fatal: fix API key configuration
    raise SystemExit("Invalid API key. Check TOGETHER_API_KEY environment variable.")

except InvalidRequestError as e:
    # Fatal: fix request parameters
    raise ValueError(f"Bad request parameters: {e}")

except RateLimitError as e:
    # Transient: retry after backoff
    print(f"Rate limited. Request ID: {e.request_id}")

except (Timeout, APIConnectionError) as e:
    # Transient: network issue, retry
    print(f"Network error: {e}")

except (APIError, ServiceUnavailableError) as e:
    # Transient: server issue, retry after delay
    print(f"Server error ({e.http_status}): {e}")

except TogetherException as e:
    # Catch-all for any other Together SDK errors
    print(f"Unexpected error: {e}")
    print(f"  HTTP Status: {e.http_status}")
    print(f"  Request ID: {e.request_id}")
    print(f"  Headers: {e.headers}")

Inspecting Error Details

from together import Together
from together.error import TogetherException

client = Together()

try:
    response = client.chat.completions.create(
        model="nonexistent-model",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except TogetherException as e:
    # Access structured error details
    print(f"Error message: {e._message}")
    print(f"HTTP status: {e.http_status}")
    print(f"Request ID: {e.request_id}")
    print(f"Headers: {e.headers}")
    print(f"Repr: {repr(e)}")

    # Check if structured API response is available
    if hasattr(e, 'api_response'):
        print(f"API response: {e.api_response}")

Key Implementation Details

• All 13 subclasses inherit from TogetherException, which itself inherits from Python's built-in Exception.
• The message parameter is polymorphic: it accepts a TogetherErrorResponse (Pydantic model), a standard Exception, a plain str, a requests.RequestException, or None.
• When the message is a TogetherErrorResponse, it is serialized to JSON via model_dump(exclude_none=True) and stored as the api_response attribute.
• The __repr__ method produces a JSON-serialized representation including the response, status, request_id, and headers -- useful for structured logging.
• InstanceError has a unique constructor that accepts a model string parameter and provides a detailed instructional message about how to start model instances.
• The SDK's AttributeError shadows Python's built-in AttributeError. When importing, be aware this may require qualified names to avoid confusion.
• Most subclasses have identical constructors (accepting message and **kwargs); they exist primarily to provide distinct exception types for except clause matching.

Related

• Principle:Togethercomputer_Together_python_API_Error_Handling
• Implementation:Togethercomputer_Together_python_Together_Client_Init
• Implementation:Togethercomputer_Together_python_ChatCompletions_Create
• Environment:Togethercomputer_Together_python_API_Credentials