Python error handling

Every SDK call either returns the typed response or raises one of two exceptions. It never raises a raw httpx error.

CargoApiError

Raised for every non-2xx response. It carries Cargo's error body.

Attribute	Description
status	HTTP status code.
code	Machine-readable error code, or None. Branch on this. Stable across releases.
type	Coarser category, e.g. ValidationError, NotFoundError.
field	On FIELD_VALIDATION errors, the offending field.
str(err)	Human-readable text for logs. Don't branch on it.

from cargo_core_api_sdk import CargoApiError

try:
    client.order_v3.create_order(order)
except CargoApiError as err:
    if err.code == "ALREADY_EXTERNAL_ORDER_ID":
        ...  # An active order already exists with this order_id.
    elif err.code == "COVERAGE_VALIDATION":
        ...  # Store or client is outside Rappi's coverage area.
    else:
        print(err.status, err.code, err)

The full list of codes per endpoint is in the API Reference.

CargoNetworkError

Raised when no response was received: DNS failure, connection reset or timeout. The default timeout is 15 seconds; change it with timeout.

from cargo_core_api_sdk import CargoClient, CargoNetworkError

try:
    client.order_v3.list_orders()
except CargoNetworkError:
    ...  # Safe to retry reads, and any create keyed by an order_id you control.

Retrying

Situation	Retry?
CargoNetworkError on a read	Yes, with backoff.
CargoNetworkError on create_order	Yes, with the same order_id.
CargoApiError with status 5xx	Yes, with backoff. Check the order status first when a write may have been partly processed.
CargoApiError with status 4xx	No, fix the request. One exception: confirming a cash return can fail with 422 and code ORDER_WITH_WRONG_DEBT while the debt is still settling. Wait a few seconds and retry that call.

Branch on err.code, not only on the status: see the return confirmation example and the error codes of the API Reference.