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/Cookbook/Debug a denied request

Debug a denied request

Read gateway errors and fix the most common access failures.

PreviousIssue and test an API keyNextUpdate product docs

On this page

Error shapeCommon causesDebug flowWhat to send support

Denied requests usually mean the gateway stopped the request before it reached the upstream. Start with the public error shape.

Error shape

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

Use code for diagnosis. Use error for human-readable context.

Common causes

SymptomLikely causeFix
Missing credentialNo API key was sent.Add the documented auth header.
Invalid credentialWrong, revoked, or malformed key.Create or rotate the subscriber key.
Subscription inactiveSubscriber is not active on a plan.Activate or update the subscription.
Limit exceededPlan quota has been reached.Upgrade, wait for reset, or enable overage.
Insufficient creditsPrepaid balance is too low.Add credits or choose another plan.
Product not foundWrong hostname or unpublished product.Use the published product hostname.

Debug flow

  1. Capture the response status and code.
  2. Confirm the request used the product hostname.
  3. Confirm the key belongs to the expected subscriber.
  4. Confirm the subscription is active.
  5. Check plan limits, credit balance, or overage behavior.
  6. Retry after any config publish or key change has propagated.

What to send support

Send:

  • product hostname
  • response status
  • response code
  • approximate request time
  • key label or last visible characters

Do not send the full API key.