TypeScript error handling

Every SDK call either resolves with the typed response body or rejects with one of two error types. It never throws a raw fetch error.

CargoApiError

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

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

import { CargoApiError } from "@rappi_cargo/cargo-core-api-sdk";

try {
  await client.orderV3.createOrder(order);
} catch (err) {
  if (err instanceof CargoApiError) {
    switch (err.code) {
      case "ALREADY_EXTERNAL_ORDER_ID":
        // An active order already exists with this order_id.
        break;
      case "COVERAGE_VALIDATION":
        // Store or client is outside Rappi's coverage area.
        break;
      default:
        console.error(err.status, err.code, err.message);
    }
  } else {
    throw err;
  }
}

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

CargoNetworkError

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

import { CargoNetworkError } from "@rappi_cargo/cargo-core-api-sdk";

try {
  await client.orderV3.listOrders();
} catch (err) {
  if (err instanceof CargoNetworkError) {
    // Safe to retry reads, and any create keyed by an order_id you control.
  } else {
    throw err; // a CargoApiError (401, 404...) is not a network problem
  }
}

Retrying

Situation	Retry?
CargoNetworkError on a read	Yes, with backoff.
CargoNetworkError on createOrder	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.