Repository navigation
[AI Gateway] document error 7003 and other error codes - #34875
Merged
Merged
Conversation
Add a troubleshooting section for error 7003 with known causes, correct the cf-aig-collect-log note for Unified Billing requests, and add related notes to the Workers bindings and dynamic routing pages. DEE-4064
🚀 Deploying Preview to Cloudflare 🚀Preview URL: https://aig-error-7003-troubleshooting.previews.developers.cloudflare.com (commit f42a99f)This URL reflects your latest Preview deploymentPreview Deployments by commit
|
github-actions
Bot
added
the
product:ai-gateway
Contributor
Add troubleshooting sections for AI Gateway error codes 2002, 2005, 2009, 2018, 2021, 2036, 2042, 2049, 2052, and 7005. Reference error 2018 from the Unified Billing rate limit on the Limits page, and point Workers AI users who receive AiGatewayError responses to AI Gateway troubleshooting. DEE-4064
github-actions
Bot
added
the
product:workers-ai
ngayerie
changed the title
Use the exact error messages for 2005, 2009, 2018, 2021, 2036, 2042, 2049, 2052, and 7005. Document the per-cause messages for 2049 and the two cases for 2021. Note that 7003 keeps the underlying HTTP status, add known causes for 403, 404, 413, and 451, and explain why the AI binding only shows the error category. DEE-4064
ngayerie
marked this pull request as ready for review
November 3, 2026 08:16
ngayerie
requested review from
a team,
ethulia,
kathayl,
kflansburg,
mattrothenberg,
mchenco,
oiricaud,
rita3ko,
shridharathi,
superhighfives and
zeke
as code owners
November 3, 2026 08:17
Contributor
AI Review✅ Reviewed Commands
|
Collaborator
Author
|
Hi @ethulia |
|
|
||
| :::note | ||
| If `cf-aig-collect-log` is set to `false`, the entire log entry (including metadata) is skipped regardless of the `cf-aig-collect-log-payload` value. Use `cf-aig-collect-log-payload: false` on its own if you only want to suppress payload storage while retaining metadata logs. | ||
| If `cf-aig-collect-log` is set to `false`, AI Gateway does not store the request and response bodies, regardless of the `cf-aig-collect-log-payload` value. AI Gateway also skips the rest of the log entry, except for requests billed through [Unified Billing](/ai-gateway/features/unified-billing/). For those requests, AI Gateway always records a log entry with billing details, such as model, tokens, cost, and status, so that it can bill the request. This entry appears in your logs without the request and response bodies. |
Contributor
There was a problem hiding this comment.
I think we could shorten the second half of this to something like "For Unified Billing requests, AI Gateway will always log the request billing details, regardless of the the collect logs headers."
Address review feedback: shorten the Unified Billing logging note, remove duplicated fixes and cross-reference hops, simplify the AI binding 7003 guidance, and make 2002/2005 H3 headings for consistent navigation.
Replace the 7003 callout with a short intro, merge duplicate resolution steps, and use actual error text in the known causes table so readers can match what they see.
The dynamic routing page moved under features/routing/ on production, so link directly to it instead of relying on the redirect.
ethulia
approved these changes
Nov 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents AI Gateway error codes on the Troubleshooting page, following the pattern of the existing
2044section, and fixes related notes.2009(provider credentials rejected), Unified Billing and credit errors (2049,2052,2021,2018,7005), account access errors (2042,2036), and provider failures (2002,2005).cf-aig-collect-log: falsenote. Requests billed through Unified Billing still get a log entry with billing details, without bodies./ai/rundoes not support dynamic routes and returns7003.2018.AiGatewayError: <CODE>: <MESSAGE>to AI Gateway troubleshooting.Related: DEE-4064
Documentation checklist