Skip to content

Exceptions

The SDK raises typed ComtradeError subclasses for every documented failure mode. The base class is un_comtrade.exceptions.ComtradeError.

API reference

The full reference is generated from the SDK's docstrings via mkdocstrings.

exceptions

SDK exception hierarchy.

This module is the single source of truth for every exception type raised by the SDK, per Architecture Freeze Question / ADR-0012 (SDK Error Hierarchy: 13 Exception Types).

The hierarchy:

ComtradeError                          ← base
├── ConfigurationError                  ← invalid config
├── AuthenticationError                 ← missing / malformed API key
│   └── AuthorizationError              ← key rejected (401/403)
├── ValidationError                     ← bad parameter / payload
├── NetworkError                        ← DNS, TLS, connection
│   ├── TimeoutError                    ← request timed out
│   ├── RetryError                      ← retry budget exhausted
│   └── RateLimitError                  ← upstream 429
├── SerializationError                  ← JSON / Decimal / Parquet
├── APIError                            ← upstream 4xx
│   └── ServerError                      ← upstream 5xx
└── UnknownError                        ← unclassified

All exceptions: - inherit from ComtradeError, - have a docstring, - accept an optional cause (preserved via __cause__), - stringify their message via str().

ComtradeError

Bases: Exception

Base class for every SDK-raised exception.

Catching this class catches every exception the SDK can raise. Consumers SHOULD prefer catching more specific subclasses.

Source code in un_comtrade/exceptions.py 
35
36
37
38
39
40
class ComtradeError(Exception):
    """Base class for every SDK-raised exception.

    Catching this class catches every exception the SDK can raise.
    Consumers SHOULD prefer catching more specific subclasses.
    """

ConfigurationError

Bases: ComtradeError, ValueError

Raised when the configuration is invalid at construction time.

Per 010_INFRASTRUCTURE_SPECIFICATION.md §3.5, the configuration is validated at construction. An invalid configuration raises ConfigurationError before the first call is issued.

Source code in un_comtrade/exceptions.py 
43
44
45
46
47
48
49
class ConfigurationError(ComtradeError, ValueError):
    """Raised when the configuration is invalid at construction time.

    Per `010_INFRASTRUCTURE_SPECIFICATION.md` §3.5, the configuration
    is validated at construction. An invalid configuration raises
    `ConfigurationError` before the first call is issued.
    """

AuthenticationError

Bases: ComtradeError

Raised when authentication is missing or malformed.

Examples: no API key configured; key not a string; key on a non-authenticated endpoint.

Source code in un_comtrade/exceptions.py 
52
53
54
55
56
57
class AuthenticationError(ComtradeError):
    """Raised when authentication is missing or malformed.

    Examples: no API key configured; key not a string; key on a
    non-authenticated endpoint.
    """

AuthorizationError

Bases: AuthenticationError

Raised when the upstream rejects the supplied credentials.

Typical upstream statuses: HTTP 401 (Unauthenticated) or HTTP 403 (Forbidden).

Source code in un_comtrade/exceptions.py 
60
61
62
63
64
65
class AuthorizationError(AuthenticationError):
    """Raised when the upstream rejects the supplied credentials.

    Typical upstream statuses: HTTP 401 (Unauthenticated) or
    HTTP 403 (Forbidden).
    """

ValidationError

Bases: ComtradeError, ValueError

Raised when a request parameter or payload fails validation.

Examples: invalid country code; invalid period; invalid flow code; invalid reporter / partner combination.

Source code in un_comtrade/exceptions.py 
68
69
70
71
72
73
class ValidationError(ComtradeError, ValueError):
    """Raised when a request parameter or payload fails validation.

    Examples: invalid country code; invalid period; invalid flow
    code; invalid reporter / partner combination.
    """

NetworkError

Bases: ComtradeError

Raised when a network-level failure occurs.

Examples: DNS resolution failure; TLS handshake failure; connection refused; connection reset; read error.

Source code in un_comtrade/exceptions.py 
76
77
78
79
80
81
class NetworkError(ComtradeError):
    """Raised when a network-level failure occurs.

    Examples: DNS resolution failure; TLS handshake failure;
    connection refused; connection reset; read error.
    """

TimeoutError

Bases: NetworkError

Raised when a request exceeds its configured timeout.

The underlying httpx.TimeoutException is preserved as __cause__ for diagnostics.

Source code in un_comtrade/exceptions.py 
84
85
86
87
88
89
class TimeoutError(NetworkError):
    """Raised when a request exceeds its configured timeout.

    The underlying `httpx.TimeoutException` is preserved as `__cause__`
    for diagnostics.
    """

RetryError

Bases: NetworkError

Raised when the retry budget is exhausted on a retryable failure.

Per ADR-0008, the default retry budget is 3 attempts.

Source code in un_comtrade/exceptions.py 
92
93
94
95
96
class RetryError(NetworkError):
    """Raised when the retry budget is exhausted on a retryable failure.

    Per ADR-0008, the default retry budget is 3 attempts.
    """

RateLimitError

Bases: NetworkError

Raised when the upstream signals HTTP 429 (rate limit exceeded).

Per ADR-0035 the upstream returns Retry-After: 1 on 429; the SDK honours this header before raising RateLimitError.

Source code in un_comtrade/exceptions.py 
 99
100
101
102
103
104
class RateLimitError(NetworkError):
    """Raised when the upstream signals HTTP 429 (rate limit exceeded).

    Per ADR-0035 the upstream returns `Retry-After: 1` on 429; the
    SDK honours this header before raising `RateLimitError`.
    """

SerializationError

Bases: ComtradeError

Raised when serialisation or deserialisation fails.

Examples: invalid JSON in the upstream response; cannot decode a numeric field into Decimal; cannot encode a record to Parquet.

Source code in un_comtrade/exceptions.py 
107
108
109
110
111
112
class SerializationError(ComtradeError):
    """Raised when serialisation or deserialisation fails.

    Examples: invalid JSON in the upstream response; cannot decode
    a numeric field into `Decimal`; cannot encode a record to Parquet.
    """

APIError

Bases: ComtradeError

Raised for upstream 4xx responses that are not auth or rate-limit.

Examples: HTTP 400 (bad request); HTTP 404 (not found); HTTP 422 (unprocessable entity).

Source code in un_comtrade/exceptions.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
class APIError(ComtradeError):
    """Raised for upstream 4xx responses that are not auth or rate-limit.

    Examples: HTTP 400 (bad request); HTTP 404 (not found);
    HTTP 422 (unprocessable entity).
    """

    def __init__(
        self,
        message: str,
        *,
        status_code: int | None = None,
        response_body: str | None = None,
        cause: BaseException | None = None,
    ) -> None:
        super().__init__(message)
        self.status_code = status_code
        self.response_body = response_body
        if cause is not None:
            self.__cause__ = cause

ServerError

Bases: APIError

Raised for upstream 5xx responses.

Typical upstream statuses: HTTP 500 (Internal Server Error), HTTP 502 (Bad Gateway), HTTP 503 (Service Unavailable), HTTP 504 (Gateway Timeout).

Source code in un_comtrade/exceptions.py 
137
138
139
140
141
142
143
class ServerError(APIError):
    """Raised for upstream 5xx responses.

    Typical upstream statuses: HTTP 500 (Internal Server Error),
    HTTP 502 (Bad Gateway), HTTP 503 (Service Unavailable),
    HTTP 504 (Gateway Timeout).
    """

UnknownError

Bases: ComtradeError

Raised for unclassified failures.

Used as the catch-all when no other exception category applies.

Source code in un_comtrade/exceptions.py 
146
147
148
149
150
class UnknownError(ComtradeError):
    """Raised for unclassified failures.

    Used as the catch-all when no other exception category applies.
    """

Hierarchy

Exception When raised
ComtradeError Base class.
ComtradeAPIError Upstream API returned a non-2xx response.
ComtradeAuthError Authentication failed (missing or invalid UN_COMTRADE_KEY).
ComtradeRateLimitError Rate limit hit; the SDK retried and gave up.
ComtradeTransportError Underlying HTTP transport failed (network, timeout).
ComtradeParseError Upstream response could not be parsed into the canonical model.
SchemaIncompatibleError Storage-layer schema check failed on append / merge.
ETLPipelineError An ETL pipeline stage failed; exc.stage_name identifies it.

Examples

from un_comtrade import ComtradeClient
from un_comtrade.exceptions import ComtradeError

try:
    with ComtradeClient() as client:
        result = client.trade.get_exports(reporter_code=699, period="2022")
except ComtradeError as exc:
    print(f"un-comtrade error: {exc}")