TRC Quotas, Rate Limits & Deterministic HTTP Error Reference

Platform Quotas, Throughput & Capacity Ceilings

Every TRC subsystem enforces explicit, predictable ceilings so automated agents and production workloads never hit undocumented silent throttling or surprise overage invoices.

Deterministic HTTP Error Codes & JSON Envelopes

All /api/v1 endpoints return structured JSON error envelopes (`{ "error": { "code": "...", "message": "..." } }`) alongside machine-readable `x-trc-*` response headers so SDKs and autonomous workflows can branch cleanly between retryable backoff and terminal configuration errors.

TypeScript (Resilient Wallet & Retry Handler)

export async function callTrcGateway(prompt: string) {
  const res = await fetch('https://api.trc.inc/api/v1/ai/deepseek/chat/completions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TRC_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'deepseek-flash',
      messages: [{ role: 'user', content: prompt }],
    }),
  });

  if (res.status === 402) {
    const body = await res.json();
    // Deterministic spend cap triggered — zero surprise overage billed
    throw new Error(`Wallet cap reached (${body.error?.code}): top up or switch to BYOK`);
  }

  if (res.status === 429) {
    const retryAfterSec = Number(res.headers.get('retry-after') || 2);
    await new Promise((r) => setTimeout(r, retryAfterSec * 1000));
    return callTrcGateway(prompt);
  }

  if (!res.ok) {
    throw new Error(`TRC API error HTTP ${res.status}: ${await res.text()}`);
  }

  const resolvedModel = res.headers.get('x-trc-model-resolved');
  const data = await res.json();
  return { content: data.choices[0]?.message?.content, resolvedModel };
}

JSON Error Envelope Examples

{
  "402_wallet_guardrail": {
    "error": {
      "code": "INSUFFICIENT_FUNDS",
      "message": "Included plan allowance and TRC Wallet balance reached $0.00. No post-paid overage was charged."
    }
  },
  "403_scope_mismatch": {
    "error": {
      "code": "INSUFFICIENT_SCOPE",
      "message": "API key does not grant required scope 'storage:write'."
    }
  },
  "429_rate_limited": {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Rate limit exceeded. Retry after window resets."
    }
  }
}

Frequently Asked Questions

Can a runaway loop in my application ever generate a surprise post-paid bill on TRC?

No. Pre-execution wallet reservations lock estimated token or media cost before upstream dispatch and settle exact micro-dollar usage on completion. Once your pre-funded TRC Wallet reaches $0.00, requests immediately return HTTP 402.

What happens if a frontier model experiences upstream provider downtime?

When automatic fallback is enabled on supported workspace routes, TRC completes your request on a healthy fallback model, surfaces actualServedModel / x-trc-model-resolved, and bills strictly at the served model’s actual rate.