Limits & errors

This page covers SwatowAPI's error shapes, common status codes, and limits, plus how to retry failed requests. Concrete limits depend on your plan and console configuration, so this page does not state fixed numbers.

Error response shape

The error shape follows the protocol surface you call, which is set by your key's group platform.

OpenAI surfaces (/v1/chat/completions, /v1/responses, /v1/images/*, etc.) return an error object:

{
  "error": {
    "type": "...",
    "message": "..."
  }
}

Anthropic surfaces (/v1/messages) return a shape with a top-level type of error:

{
  "type": "error",
  "error": {
    "type": "...",
    "message": "..."
  }
}

When debugging, read error.message first, it usually states the cause. Use error.type for programmatic classification.

Common status codes

Status	Meaning	What to do
401	Missing or invalid key.	Check Authorization: Bearer sk-... (Gemini native uses x-goog-api-key). Confirm the key is valid in the console.
404	The endpoint is not available for your key's group platform. For example, images on a non-OpenAI group, or count_tokens on an OpenAI group.	Use a key whose platform matches the endpoint, or switch to that platform's equivalent endpoint. See Authentication.
429	Rate limited.	Retry with backoff, see below. Limits depend on your plan, check the console.
5xx	Upstream or gateway error.	The gateway may have already fallen back; if it still returns 5xx, retry with backoff. See Routing & fallback.

Failed and timed-out requests are not billed. See Billing.

Retry and backoff

Retry on 429 and 5xx, using exponential backoff with jitter so retries do not stampede.

• Start from a base interval (for example 1 second), double on each retry, and add random jitter.
• Cap it (for example at most 5 retries, with a per-attempt ceiling), then surface the error.
• If the response carries Retry-After, prefer the wait it indicates.
• 401 and 404 are configuration errors, do not retry: fix the key or endpoint first.

TIP

On 5xx, the gateway may already have fallen back to another available channel for you. Client-side retry sits on top of that as a safety net; the two do not conflict.

Request body size limit

The request body has a maximum size, configured by the deployment (this page does not state a fixed number). Exceeding it typically shows up as a rejected request. If you need a larger body, check the console or ask your operator for the limit.

Limits depend on your plan

Rate limits and other quotas depend on your plan and console configuration; this page does not list concrete numbers. Check the console for your current limits.

Related

• Routing & fallback — how failures fall back automatically, and the trace id.
• Authentication — keys, groups, and platforms, and the cause of 404.
• Billing — no charge on failure or timeout.