Usage limits
Correlate a gateway denial, identify the governing contract, and choose a safe operational response.
Limit definitions are repo-owned Business contract. A denial and its recorded usage are platform-owned runtime facts. Diagnose the fact before changing the contract.
Capture the request identifiers
On a denied gateway response, retain the response status, code, limitCode,
X-FS-Decision-Id, request id, environment, route, and caller. Limit-class
responses also carry a self-describing _fs block.
{
"code": "rate_limited",
"limitCode": "rate_limit",
"_fs": {
"limitClass": "rate",
"reaction": "backoff_retry",
"retrySafe": true,
"decisionId": "dec_...",
"requestId": "req_..."
}
}
Then ask the platform to explain the recorded request:
farthershore denial show acme <requestId> --format json
farthershore analytics log acme --domain denials --range 1h --limit 100 --format json
farthershore usage summary acme --format json
denial show is the narrow diagnostic. Analytics establishes whether the same
failure is isolated or widespread. Usage establishes the current business-level
picture; none of these commands changes a limit.
React by limit class
| Class | Typical response | Safe reaction |
|---|---|---|
quota | Period budget exhausted | Wait for reset or offer an appropriate plan change. Do not hot-loop. |
rate | Short-window velocity cap | Honor Retry-After, add jitter, and retry. |
concurrency | Too many requests in flight | Queue or back off until a slot clears. |
capacity | One request is too large | Reduce or split the request before retrying. |
spend | Funding exhausted on a block plan (credit_exhausted) | Wait for a top-up or the next issuance, or offer an overage/plan change. |
adaptive | Upstream provider throttle | Back off or use a safe fallback; the customer cannot raise the provider's cap. |
Do not branch only on HTTP status. 429 can mean rate or concurrency, and 402
can mean quota or spend. _fs.limitClass and _fs.reaction carry the semantic
meaning for a classified limit denial.
A 503 ending in _unavailable or _unprovable is a fail-closed dependency
or release-proof failure rather than a limit. 422 invalid_admission_knob and
422 admission_bound_exceeded mean the client's output knob (max_tokens and
aliases) is malformed or above the route's declared bound — fix the request.
See Monetary admission. Retrying a
destructive platform operation because a gateway dependency failed is not a
valid limit response.
Resource counts are backend-reported state
If a plan caps persistent resources, the Business program declares the resource and limit, while the running backend reports the authoritative count after its own mutation:
farthershore resource-count report acme projects \
--subscription <subscriptionId> \
--count 42 \
--environment <environmentId> \
--format json
Use the backend runtime SDK for normal request-path reporting. The CLI command is an operator surface for explicit reconciliation; it is not a substitute for a race-safe create/delete transaction in your application.
Change the contract only when the contract is wrong
Read the accepted route and contract first:
farthershore business routes acme --env production --format json
farthershore business contract acme --env production --format json
farthershore plan list acme --format json
If the declared capacity, route grant, meter, or spend policy is wrong, edit the Business program, test in preview, and release forward. Do not search for an imperative limit-update command.