Routing & fallback

SwatowAPI fronts 50+ upstream channels behind one set of compatible endpoints. You pick the model, the gateway picks the channel: it auto-routes by cost and availability, falls back automatically when an upstream fails, and stamps every call with a trace id for tracing. This page explains what you control versus what the gateway does for you.

What you control vs what the gateway controls

The boundary is simple:

• You control: which key you call with (this fixes your group and protocol surface), which model you request, and the request parameters. Use GET /v1/models for the exact model IDs.
• The gateway controls: which upstream channel carries a given call, and which channel it falls back to on failure. This is transparent to you. Your request and response shapes do not change.

In short: you say which model you want, the gateway decides which channel runs it.

Auto-route by cost and availability

A single model may be served by more than one upstream channel. On each request, the gateway routes across the currently available channels, weighing cost and availability. You do not need to, and cannot, hand-pick a specific channel: name the model and the gateway routes it.

TIP

Not sure of a model's exact model ID? Call GET /v1/models and trust the server response. See Models.

Automatic fallback on failure

When an upstream channel fails or times out, the gateway automatically falls back to another available channel serving the same model. The caller does not notice.

• Fallback happens on the gateway side. Your request shape does not change.
• Failed and timed-out requests are not billed. See Billing.
• If no available channel can complete the call, the gateway returns an error to you. For the error shape, status codes, and retry guidance, see Limits & errors.

Fallback improves reliability, but it is not unlimited retry. For 429 and 5xx, your client should still retry with backoff. See Limits & errors.

Per-call tracing: the trace id

Every call carries a trace id. It links the request to its metering and reconciliation entry in the ledger, which makes debugging and usage auditing straightforward. Combined with the public channel status, you can see both the platform's overall channel health and the trace of your own individual calls.

Public channel status

Channel and health status is public. When a model looks unstable, check it against the public channel status to tell whether the cause is an upstream fluctuation on the platform side or something on your side (for example, a key whose group platform does not match the endpoint, see Limits & errors).

Next

• Models — models on sale, and how to get exact IDs from GET /v1/models.
• Limits & errors — error shape, status codes, and retry guidance.
• Billing — pay per call, no charge on failure, one ledger.