Error catalog

The mental model

Every non-2xx response from https://api.fightclub.pro/v1 carries a single JSON object with one top-level error key. The shape is stable across all endpoints. You read three fields on every error and two more on specific families. The type tells you the broad class and usually maps 1:1 to the HTTP status. The code is the stable machine-readable string you branch on. The message is human text for your logs and can change without notice.

The error envelope

Three fields are always present: type, code and message. param appears only on field-validation errors and names the offending request field. retry_after_seconds appears only on rate-limit errors and mirrors the integer Retry-After response header.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_model_ref",
    "message": "model is not a fc:/match:/slot:/dyn: ref.",
    "param": "model"
  }
}

type

Always present. One of the eight families below (plus not_implemented for endpoints still on the roadmap). Maps to the HTTP status in almost every case.

code

Always present. The stable identifier you branch on. Unique per failure mode.

message

Always present. Human-readable detail for logs. Not a stable contract; do not parse it.

param

Present on field-validation errors only. The name of the request field that failed (model, messages, metadata, etc.).

retry_after_seconds

Present on rate-limit errors only. Integer seconds to wait before retrying. Mirrors the Retry-After header on the same response.

The request id

Every response, success or failure, carries an X-Request-Id response header (value prefix req_). It is a header, never a body field. Capture it on failures and quote it in support requests. If you set your own X-Request-Id on the request, Ringside echoes yours back so you can correlate against your own traces.

# Pull the request id off any response
curl -sD - https://api.fightclub.pro/v1/chat/completions \
  -H "Authorization: Bearer ko_REDACTED" \
  -H "Content-Type: application/json" \
  -d '{"model":"fc:openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}' \
  | grep -i '^x-request-id:'
# x-request-id: req_8f2c1a...

Type families

Eight families cover the catalogue, with not_implemented reserved for roadmap endpoints. The family is a coarse signal: it tells your retry logic whether the failure is yours to fix (4xx) or ours to recover from (5xx). For anything beyond a retry/no-retry decision, switch on the code.

Complete code reference

Grouped by area. Status is the HTTP code, type is the envelope family. Codes shared across many endpoints (invalid_api_key, not_found, malformed_json, metadata_too_large) are listed once under the area where you hit them first, but they behave identically everywhere.

Authentication and authorization

Customers

Chat completions

The embeddings and rerank endpoints reuse the same auth and wallet codes plus their own validation: missing_input, invalid_input and input_too_large on embeddings (array <=2,048 items, each <=100,000 chars), and unsupported_rerank_model and too_many_documents on rerank (<=1,000 documents). Moderation only returns invalid_api_key, invalid_json and missing_input, and meters at $0.

Rate limits

Four enforcement layers run, lowest ceiling wins: edge per-IP, per-client-token, per-developer and per-customer. A 429 always carries an integer Retry-After header, and the body carries retry_after_seconds. Successful responses carry X-RateLimit-Remaining. There is no X-RateLimit-Limit or X-RateLimit-Reset.

Wallet and budget (402)

Every metered response (success or some 402s) carries X-Ringside-Wallet-Balance and X-Ringside-Wallet-Deducted so you can watch the balance fall and pre-empt the empty-wallet 402 before it bites.

Vector stores and RAG

Webhooks

These are errors from the webhook management API. They are separate from delivery signature verification, which happens on your receiver: validate the X-FC-Signature header (t=<unix>,v1=<hex>) constant-time, accept either digest during a rotation grace and reject stale timestamps. See Receive and verify webhooks.

Assistants, threads and runs

Batch

A batch caps at 50,000 requests. Failed lines land in error_file_id; download both output_file_id and error_file_id via GET /v1/files/{id}/content.

Files

Brains

Worked example: handling the common failures

A real client catches the credential, validation, rate-limit and wallet families separately, captures the request id and retries only the recoverable ones. This is the minimum production-grade handler.

import time
from openai import OpenAI, APIStatusError

client = OpenAI(
    base_url="https://api.fightclub.pro/v1",
    api_key="ko_REDACTED",
)

def chat_with_retry(messages, attempts=4):
    for i in range(attempts):
        try:
            return client.chat.completions.create(
                model="fc:openai/gpt-4o-mini",
                messages=messages,
                extra_headers={"FC-Customer": "cus_42"},
            )
        except APIStatusError as e:
            req_id = e.response.headers.get("x-request-id")
            err = (e.body or {}).get("error", {})
            code = err.get("code")

            if e.status_code in (401, 403):
                raise RuntimeError(f"auth/permission: {code} (req {req_id})")
            if e.status_code == 402:
                # wallet_empty / customer_wallet_empty / customer_budget_exceeded
                raise RuntimeError(f"out of funds: {code} (req {req_id})")
            if e.status_code == 429:
                wait = int(e.response.headers.get("retry-after", "1"))
                time.sleep(wait)
                continue
            if 500 <= e.status_code < 600:
                time.sleep(2 ** i)  # backoff on api_error
                continue
            # 400/404/409/422 are your bug: do not retry
            raise RuntimeError(f"bad request: {code} param={err.get('param')} (req {req_id})")
    raise RuntimeError("exhausted retries")

Retry policy by status

Related