Limits and quotas

How to read this page

Two kinds of limit exist in Ringside, and it helps to keep them apart. The first kind is a fixed validation ceiling baked into the request handler. An embeddings call may carry at most 2,048 inputs and a chat message body may serialize to at most 100,000 bytes. You cannot raise these. Exceed one and the request is rejected before any model is called, so you are not billed. The second kind is a configurable quota such as your developer rate limit, a customer rpm_limit or a monthly_budget_usd. Those are set per account and enforced at request time, and the rate ones return 429 with a Retry-After header. This page documents the fixed ceilings in full and points at the configurable ones.

Chat and message limits

The chat completions endpoint caps the serialized size of the messages you send and the number and size of multimodal content parts inside any one message. The byte cap is measured against the JSON-serialized messages array, so a few large base64 image data-URLs will hit it long before a wall of plain text would.

The image and document size checks decode the base64 payload of a data: URL and compare the byte length against the cap before the bytes ever leave the edge. An fc_file:<id> reference or a file_id is resolved server-side and the same 20 MB document cap applies to the fetched blob. Plain https:// URLs are passed through to the provider unmeasured. Only application/pdf is accepted for file parts today; any other mime returns 400 invalid_content_part.

File upload limits

Files uploaded through POST /v1/files (for batch input, vector-store ingestion or chat attachment) have their own ceiling that is much larger than the inline content-part caps. Use a file upload plus an fc_file: reference when an asset is bigger than the inline data-URL caps allow.

Embeddings limits

The embeddings handler bounds both the array length and each string length before the upstream call, so one request cannot amplify cost or pressure the heap with an unbounded array or a multi-megabyte string. An empty input array is also rejected.

{
  "error": {
    "type": "invalid_request_error",
    "code": "input_too_large",
    "message": "Each 'input' item must be \u2264 100000 characters",
    "param": "input"
  }
}

Rerank limits

Rerank is the second pass of two-stage retrieval (vector search, then rerank). The document count and the query and per-document character lengths are all capped. A request is billed as one search unit, so the document cap is also a cost ceiling.

Vector store limits

Vector stores ingest files asynchronously and carry their own metadata. The file-batch limit bounds how many files one ingest call can attach; ingestion status moves through pending, in_progress, completed, failed or cancelled per file.

Brains limits

Brains endpoints are covered by the standard /v1 rate limits (the four enforcement layers on the rate-limiting page); there is no separate per-endpoint Brains limit today.

Conversation and thread limits

Conversations (conv_) and OpenAI-compatible threads (thread_) share a hard message cap. When a conversation reaches it, no new turn may start. A turn also takes a row-level lock so two concurrent turns cannot interleave on the same conversation; the lock self-expires so a crashed client never wedges a conversation permanently.

Batch limits

A batch references an input file uploaded with purpose=batch, targets one of three endpoints and runs in a fixed 24-hour window. The only valid completion_window value is "24h". Batches run at half the synchronous per-call price, but only above a small request floor so a one-line "batch" cannot claim the discount on otherwise-synchronous traffic.

Metadata object limits

Most Ringside resources (customers, vector stores, batches, conversations, assistants, threads) accept a free-form metadata object. The serialized size cap differs by surface, but the per-object key and value shape is uniform.

The size check runs Buffer.byteLength(JSON.stringify(metadata)) against the per-surface cap. The 2 KB conversation cap is deliberately tighter than the 4 KB default because conversation metadata is stored per row and a conversation can carry up to 5,000 messages.

Client token limits

Client tokens are short-lived, per-customer JWTs that a browser presents directly to /v1/* with the Authorization: Client <jwt> scheme. Your developer key mints them server-side via POST /v1/customers/{id}/client_tokens and must hold the api:client_tokens scope. Mint rate, token lifetime and the token's own per-minute rate are all bounded.

The token rpm is also clamped to the owning customer's rpm_limit: if you request rpm: 600 but the customer is capped at 120, the mint fails with rpm_exceeds_customer_cap. So the effective ceiling is the lower of 600 and the customer's own limit. Optional bind_ip pins the token to the minting client IP; origin_allowlist restricts which browser origins may use it. The token jti carries the ctok_ prefix.

curl https://api.fightclub.pro/v1/customers/cus_42/client_tokens \
  -H "Authorization: Bearer ko_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": 1800,
    "rpm": 120,
    "scope": ["chat", "conversations"],
    "origin_allowlist": ["https://app.example.com"]
  }'

Pagination limits

List endpoints are cursor-paginated. Pass limit to set the page size and after set to the previous response's next_cursor to page forward. The response shape is { "data": [...], "has_more": boolean, "next_cursor": string | null }; there is no object: "list" envelope field.

A limit outside [1, max] is clamped into range rather than erroring, so passing limit=500 on a standard list simply returns 100 rows. Some lists also accept before, status, order_by and external_id filters; see the per-endpoint reference for which apply.

Rate limits and budgets

Rate limiting is layered. Four enforcement points each hold their own counter and the lowest remaining wins: edge per-IP, then per-client-token, then per-developer, then per-customer. When any layer is exhausted the request returns 429 rate_limit_error with a Retry-After integer-seconds header and a retry_after_seconds field in the body. The response also carries X-RateLimit-Remaining for the current window. There is no X-RateLimit-Limit or X-RateLimit-Reset header.

Spend ceilings are separate from rate ceilings. A customer monthly_budget_usd over its limit returns 402 customer_budget_exceeded; an empty customer wallet returns 402 customer_wallet_empty; an empty developer API pool returns 402 wallet_empty. The per-customer rpm_limit and tpm_limit are the configurable rate quotas referenced by the client-token clamp above. Unlike the validation ceilings on this page, these are set per account and you raise them by changing the customer or developer record.

Quick reference