Response & deny codes

When the platform denies a request it returns stable base fields: a human-readable error plus a machine-readable code. Limit decisions may also include limitCode and an _fs envelope with reaction, retry safety, origin, decision id, and limit metadata. Branch on typed SDK helpers and code, never the message. The frontend SDK exposes the canonical gateway vocabulary as FS_DENY_CODES.

{ "error": "Rate limit reached for this key.", "code": "rate_limited" }

import {
  FartherShoreApiError,
  FS_DENY_CODES,
} from "@farthershore/farthershore-js";

try {
  await fs.route.get("/v1/cron-jobs");
} catch (err) {
  if (err instanceof FartherShoreApiError) {
    switch (err.code) {
      case FS_DENY_CODES.credit_exhausted:
        return showFundingExhausted();
      case "route_not_enabled":
        return promptUpgrade();
    }
  }
}

Platform deny wire-codes (FS_DENY_CODES)#

The canonical deny code values. Grouped by concern; the HTTP status the platform returns alongside each is in the table.

Retryability is decision-specific#

Use the public guards on the caught error, not a raw status or code. _fs.reaction and _fs.retrySafe are authoritative when present, so a structured decision can make a nominal 429/503 unsafe to replay. Only when no structured envelope exists does the SDK fall back to the transient code/status classification below.

import { isRetryable, isThrottled } from "@farthershore/farthershore-js/errors";

try {
  await fs.route.get("/v1/cron-jobs");
} catch (err) {
  if (!isReplaySafeOperation()) throw err;
  if (isThrottled(err)) return backOffAndRetry(); // honor Retry-After
  if (isRetryable(err)) return retryWithBackoff(); // transient fallback
  throw err;
}

Fallback-transient codes are limit_allocator_unavailable, rate_limited, invalid_entitlement_shape, unsupported_constraint_schema, enforcement_dependency_unavailable, concurrency_limit_exceeded, concurrency_context_unavailable, concurrency_coordinator_unavailable, geo_context_unavailable, resolver_rate_limited, resolver_unavailable, credential_resolver_miss_rate_limited, provider_throttled.

Never automatically replay a mutation unless its idempotency contract proves the same request cannot duplicate the effect.

Upgrade affordance — limitCode#

A limit deny also carries a separate limitCode field (an upgrade-affordance value, not a wire code) telling the UI what kind of limit was hit. The fixed values:

Runtime verification statuses#

These come from the upstream's @farthershore/backend, not the platform deny path — when fs.verifyRequest() / fs.middleware() rejects a request the platform forwarded. Verification is fail-closed: every failure maps to one status.

FartherShoreError.code carries the precise runtime reason (for example, invalid_token or jwks_unavailable). statusForCode(code) supplies the default mapping and explicitly handles body_too_large and surface_not_allowed; subject and permission helpers construct their own 403 errors. There is no fail-open branch.

Origin availability — origin_unavailable and origin_timeout#

These two codes describe the hop between the gateway and your backend. They are always the platform's own envelope — the gateway never relays your hosting provider's error page (Railway's Application not found, a raw HTML 502), so a caller can always tell "the origin is not there" from "your application said no". Neither is ever billed to the customer, and any reservation the request took is released.

Both carry Retry-After and an _fs envelope with { "retrySafe": true, "reaction": "backoff_retry" }:

{
  "error": "Origin unavailable",
  "code": "origin_unavailable",
  "_fs": { "retrySafe": true, "reaction": "backoff_retry" }
}

Other stable operational codes#

Not every stable code is a member of the closed gateway-denial catalog. origin_unavailable is a gateway routing failure: the selected environment has no usable backend origin and returns 503 without falling back to production. Backend verification and authorization also use stable runtime codes such as context_unverified, principal_required, member_subject_required, service_subject_required, and surface_not_allowed. Diagnose those at the signature/principal/application boundary rather than adding them to FS_DENY_CODES. A usage payload from an outdated @farthershore/backend that lacks the served-identity block receives a permanent 410/422 unsupported_usage_schema with expected_schema_version and received_schema_version — upgrade the SDK; the event is never queued, quarantined, or backfilled.

HTTP status taxonomy#

How the statuses map to categories across both surfaces:

How to debug a denial#

1. Read the code (not the message).
2. Call isRetryable(err) and require replay-safe operation semantics. Honor the structured decision and Retry-After before retrying.
3. If it's a limit (limit_exceeded / credit_exhausted / resource_count_limit_exceeded), read limitCode and surface an upgrade or funding affordance.
4. If it's a 422 admission code, the client's output knob is malformed or above the route's declared bound — see Monetary admission.
5. If it's a 401 from your own upstream, it's a verification failure — check FartherShoreError.code and that FS_RUNTIME_TOKEN is current.
6. Confirm the subscriber's key, subscription, and plan limits.