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/Operate/Gateway response codes

Gateway response codes

Understand the public error shape returned by the gateway.

PreviousTroubleshootingNextMeter naming

On this page

Common code categoriesHow to debug a codeClient behaviorSupport behavior

Gateway errors use a compact JSON shape:

{
  "error": "Human-readable message",
  "code": "machine_readable_code"
}

The exact set of codes can evolve, but the categories are stable.

Common code categories

CategoryMeaningSubscriber action
AuthenticationMissing or invalid key.Send the correct API key.
AuthorizationSubscription or plan does not allow access.Check plan and subscription state.
LimitsUsage, concurrency, or quota limit reached.Wait, upgrade, or enable overage.
CreditsNot enough prepaid balance.Add credits or change plan.
RoutingProduct or upstream route was not found.Check hostname and path.
RuntimeGateway could not safely complete enforcement.Retry or contact support.

How to debug a code

  1. Identify whether the response came from the gateway or upstream.
  2. Read the code.
  3. Check the subscriber key and subscription.
  4. Check plan limits or credits.
  5. Retry after config or key changes have propagated.

Client behavior

Client integrations should treat gateway denials as expected API responses, not network failures. Log the code and expose the error message to operators.

Support behavior

Support should ask for the response code, request time, hostname, and key label. Never request the full API key.