Service eligibility and regional restrictions
PuppyIP serves only compliant overseas businesses and their authorized personnel. Proxy services are not available in mainland China. The service may only be used for lawful business activities outside mainland China. Use of this service within mainland China is prohibited.
Hosting a proxy IP or server overseas does not change these restrictions. The service must not be provided to end users in mainland China through relaying, forwarding, sharing or resale. Before use, read the Terms of Service.
Key Takeaways
- Cloudflare documents a new mapping for provider credential rejections on REST POST /ai/run: HTTP 401 with error code 2009. Google Vertex requests no longer retry the provider after this rejection.
- A provider credential rejection on Unified Billing returns 503, but a 503 by itself does not prove that a key is invalid. Check the route and response details.
- On provider-native requests, BYOK supplies a stored key only when the request omits the provider authorization header. A placeholder value in that header is forwarded.
- Unified Billing checks recognized request credentials, then the default stored BYOK key, and then Cloudflare-managed credentials if fallback is allowed. A non-default alias does not prevent fallback on this path.
Read the status in the context of the request path
The documented scope is provider credential rejection on REST POST /ai/run. ElevenLabs moves from HTTP 403 with UserCredentialsError to HTTP 401 with error code 2009; Google Vertex moves from HTTP 500 with upstream retries to the same 401 and 2009 response without retrying the provider; other providers move from HTTP 402 or provider-specific statuses to HTTP 401 with error code 2009.
This mapping comes from the Cloudflare announcement dated October 6, 2026 on the page. This guide checks the current BYOK and Unified Billing documentation as of November 11, 2026. The announcement does not give an account-by-account switchover time, so it does not establish the response any particular account will return now.
Do not apply this mapping to every AI Gateway endpoint or every 401. Confirm that the request went to REST POST /ai/run, and retain the response error code and request ID.
Cloudflare separately documents HTTP 503 when a provider rejects credentials while using Unified Billing. That mapping does not mean every 503 is a key error; without evidence of a credential rejection, also check the route, response body and request logs.
Check gateway authentication and provider credentials separately
For an authenticated gateway, provider-native requests use cf-aig-authorization to authenticate with Cloudflare AI Gateway. It is not the upstream model provider's key. If entry-point authentication fails, check the Cloudflare credential for that endpoint separately from the upstream provider credential.
Provider-native BYOK uses the stored key only when the request has no provider authorization header. If a provider authorization header is present, the gateway forwards its value to the provider; a placeholder string is forwarded too and can cause authentication to fail. To use stored BYOK, remove the provider authorization header but keep cf-aig-authorization.
Check where BYOK keys are stored and how they are found
BYOK keys are stored with Secrets Store. Before configuring one, make sure the gateway is authenticated and the operator has permission to create and deploy Secrets Store secrets. In the dashboard, go to AI, AI Gateway, the target gateway, Provider Keys and Add API Key; choose a provider, enter its key and save.
Deleting a stored key immediately stops requests that depend on it. Prepare a replacement key or another credential path before deletion; the documentation does not promise that deletion or replacement will avoid interruption.
Check Unified Billing credential precedence and aliases
On a Unified Billing path, AI Gateway first uses request credentials it recognizes for that provider and endpoint. If none are present, it checks the provider's default BYOK key on the gateway. If neither applies and fallback is allowed, it uses Cloudflare-managed credentials and deducts the cost from the Unified Billing balance.
Provider-native endpoints also differ in which credential headers they recognize. For example, Anthropic Messages recognizes x-api-key, not Authorization: Bearer, as provider credentials. A Bearer header alone does not prevent stored-key lookup or Unified Billing fallback.
cf-aig-byok-alias selects a non-default alias only for direct provider-passthrough requests. Unified Billing paths such as env.AI.run() and /ai/v1/chat/completions check only the default alias. If that key is missing, a request may fall back to Unified Billing even when production or testing aliases exist.
Stop third-party provider fallback when needed
To prevent third-party provider requests from falling back to Unified Billing, enable Require provider credentials on the gateway; the API configuration field is byok_only: true. To control one third-party request, send the cf-aig-no-wholesale: true header. This request header cannot relax an enabled gateway setting, and setting it to false does not override the gateway requirement.
When this requirement is enabled and neither the request nor gateway has applicable provider credentials, the request returns HTTP 400 with error code 2044 instead of using Cloudflare-managed credentials. This differs from HTTP 401 error 2009 after a provider rejects supplied credentials. Workers AI requests do not use provider credentials, and this setting does not block them or change their billing mode.
Before retrying, verify the endpoint type, whether the provider authorization header is absent, whether Unified Billing has a default BYOK key, and whether the response includes 2009 or another code. Correct the confirmed issue and send one minimal request. Record the request ID and credential path in troubleshooting notes, but do not record or share keys. Changing a proxy exit does not fix a key the provider rejects or change platform eligibility, charges or usage rules.
Sources
Frequently Asked Questions
What charges apply if a request falls back to Unified Billing?
Third-party provider requests using Cloudflare-managed credentials draw on the Unified Billing balance. The documentation checked for this guide applies a 5% fee to credit purchases: buying $100 in credits results in a $105 charge. Provider inference prices pass through without a markup. Keep this separate from the provider bill for your own key, and do not assume an error response proves a charge occurred; check the actual billing record.
Does AI Gateway find an API-created BYOK secret by its secret_id?
No. Name the Secrets Store secret {gateway_id}_{provider_slug}_{alias} and use the same provider_slug and alias in the provider configuration. Runtime lookup relies on that naming convention, not the secret_id returned by Secrets Store.