Farther ShoreDocs
Go to Farther Shore
Getting startedCore conceptsLaunch checklist
ProductsUpstream routingEnvironmentsDeveloper portals
Billing strategiesPlans and limitsSubscribersAPI keys
Gateway enforcementUsage meteringLimits and creditsGateway sharding
Launch a request-counted product15mAdd monthly included usageAdd subscription plus overageCreate a prepaid credits productMeter AI token usageAdd a custom meterIssue and test an API keyDebug a denied requestUpdate product docsPrepare for launch
TroubleshootingGateway response codesMeter namingPlatform docs publishing
Status
Docs/Enforce & Meter/Gateway enforcement

Gateway enforcement

How live requests are authenticated, enforced, routed, and metered.

PreviousAPI keysNextUsage metering

On this page

Request flowWhy enforcement is compiledWhat can be enforcedError shapeCaching behaviorUpstream failures vs gateway denialsSharding

The gateway is the runtime that protects live products. It runs in front of the upstream API and decides whether each subscriber request should be forwarded.

Request flow

For a typical request, the gateway:

  1. receives traffic on the product hostname
  2. applies unauthenticated abuse protection
  3. resolves the product
  4. extracts and validates the API key
  5. resolves the subscriber and active subscription
  6. loads compiled entitlement and shard policy
  7. checks features, limits, credits, and concurrency constraints
  8. forwards allowed traffic to the upstream
  9. records usage and reconciles actual usage when available
  10. emits usage events for core ingestion

Why enforcement is compiled

Core stores the source of truth. The gateway needs a fast runtime shape.

When products, plans, subscriptions, or keys change, core publishes compiled runtime artifacts. The gateway reads those artifacts from edge configuration and caches them. That avoids a control-plane request on every API call.

What can be enforced

The gateway can enforce:

  • missing or invalid credentials
  • inactive subscriptions
  • plan feature access
  • monthly or period usage limits
  • overage rules
  • prepaid credit requirements
  • concurrency limits
  • request or usage meter constraints

Error shape

Gateway errors use a flat public shape:

{
  "error": "Usage limit exceeded",
  "code": "usage_limit_exceeded"
}

The error is for humans. The code is for client logic and support workflows.

Caching behavior

Gateway configuration is cached so requests stay fast. Most product and key changes propagate through edge publishing rather than direct gateway calls.

If a recent change is not visible yet, wait for the publish/refresh path and retry with a fresh request. Do not assume the upstream is broken until you know whether the gateway denied the request.

Upstream failures vs gateway denials

Gateway denials usually return a platform code. Upstream failures usually look like your API's own error response.

When debugging, first identify whether the request was denied before forwarding or forwarded and failed upstream.

Sharding

Durable Objects coordinate hot runtime state such as usage allocation and concurrency. High-traffic products can be spread across multiple shards so one object does not become the bottleneck.

See Gateway sharding for the product-facing model.