Errors & limits

Start with the HTTP status, then identify the specific failure before retrying. An invalid key, an exhausted budget, and a temporary rate limit need different fixes.

Identify the error

Read the response body and headers. For gateway denials, X-Straitly-Error-Code carries the named reason, such as quota_exceeded or budget_exhausted. Do not assume error.code in the JSON body always contains that string.

The body shape depends on the endpoint dialect and where the error originated. Anthropic-format errors differ from OpenAI-format errors; upstream errors can vary too.

HTTP/1.1 402 Payment Required
X-Straitly-Error-Code: quota_exceeded
X-Straitly-Action: raise_cap

{
  "error": {
    "message": "This key has reached its daily spend cap.",
    "type": "invalid_request_error",
    "code": 402
  }
}

Illustrative gateway denial. Keep the error message and request context for diagnosis, but never log your Authorization header or raw API key.

Error reference

Retry safely

• For request-rate or concurrency limits, respect Retry-After when it is present. If no usable retry hint is returned, use exponential backoff with jitter and a maximum attempt count.
• Stop automatic retries for invalid credentials, exhausted credits, spending caps, and lifetime budgets. Waiting a few seconds does not fix these conditions.
• Check whether your SDK already retries. Adding an outer retry loop can multiply attempts unexpectedly.
• A timeout can leave the outcome uncertain. Inspect request history and avoid blindly repeating external tool actions or other side effects.
• After a partial stream, treat a retry as a new generation. Do not silently append the new answer to the old one.

Not every 429 is temporary: budget_exhausted needs a budget change. An HTTP retry hint is not permission to bypass a spending limit.

Rate and concurrency

Account limits are shared across your keys. Requests per minute counts how often you send requests; concurrency counts how many are still running. A long streaming response occupies an in-flight slot until it ends.

Your account can have custom limits. Use the Limits page for your current values and higher-limit requests instead of relying only on this default table.

Rate-limit denials carry Retry-After and may include X-RateLimit-Limit and X-RateLimit-Remaining. Do not assume every error or successful response has the same headers.

Starter

300 / minute64 requests in flight. Default account limits.

Growth

1,000 / minute200 requests in flight.

Scale

3,000 / minute500 requests in flight.

Spending controls

Daily caps track billed spend, including charges still settling. The displayed tally can lag by about a minute, so treat the cap as a spend control rather than an exact, instantaneous cutoff.

Review limits intentionally before raising them. A capped key stopping does not mean that every other key on the account has stopped.

Account balance

Prepaid creditsShared by requests billed to the account. Exhaustion blocks new paid requests.

Daily key cap

UTC dayEach key has its own optional cap. The daily window resets at the UTC day boundary.

Child-key budget

LifetimeA fixed budget does not reset daily or each minute. Review it before allowing more spend.

Diagnose a failure

• Record the time, model ID, endpoint, HTTP status, and X-Straitly-Error-Code when present.
• Inspect Activity for a recorded request and its upstream error. Not every rejected or network-failed attempt is guaranteed to have an individual history row.
• Failed requests are not billed. For an interrupted stream, inspect the final recorded status and charge instead of assuming the client-side error defines the bill.
• When contacting support, include a request identifier if available and a redacted error message. Never include a raw key or a setup command containing one.