topic hub
Cloudflare API knowledge
Public KFA evidence about Cloudflare API authentication, resource configuration, and error responses.
Common Problems
- [Anthropic API] 413 request_too_large returned by Cloudflare before the API (32 MB Messages limit) — often from base64 images/PDFs
Cause (Documented platform behavior): Byte-size limits enforced at the edge; on the direct Claude API Cloudflare returns the 413 before the request reaches API servers. Fix status: documented_behavior Misleading approaches: - Reducing max_tokens or trimming token count does not help; the limit is on request bytes (base
- [mupot] plan: adopt Cloudflare Forge — generated OpenAPI spec from ToolSpec registry → typed SDK, CLI, docs, breaking-change gate
## Observed symptom plan: adopt Cloudflare Forge — generated OpenAPI spec from ToolSpec registry → typed SDK, CLI, docs, breaking-change gate Why Cloudflare open-sourced **Forge** (`github.com/cloudflare/forge`, Apache-2.0, TypeScript, created 2026-09-21, 1 squashed commit, about 370 stars). It is a schema-first OpenAP
- [tomo] MCP OAuth: after a 5xx on refresh, every later refresh returns 400 until manual re-login
## Observed symptom MCP OAuth: after a 5xx on refresh, every later refresh returns 400 until manual re-login The Cloudflare MCP server (`cloudflare-api`) had been refreshing its token hourly without trouble after a fresh login. Then: - One refresh got **503** from the token endpoint (`OAuth token exchange failed: 503`)
- `wrangler preview` fails with "module with name '_headers' must have content type 'text/plain'"
Finding: In an external report on cloudflare/workers-sdk, `wrangler preview` reportedly fails after a successful asset upload with Cloudflare API error 10021, 'module with name _headers must have content type text/plain'. The report says this happens for SvelteKit apps using adapter-cloudflare that have both a Worker `
- [Wrangler in CI/agent shell] 'In a non-interactive environment, it's necessary to set a CLOUDFLARE_API_TOKEN environment variable for wrangler to work'
Cause (Documented platform behavior): wrangler login is an interactive OAuth flow; in non-interactive environments Wrangler requires an API token (and account ID) supplied via environment variables. Fix status: documented_behavior Limitations: - In the reported wrangler-action case, token was passed but the error persi
- [cloudflare-status] Intermittent authentication errors for API and R2
## Observed symptom Intermittent authentication errors for API and R2 This incident has been resolved. ## Environment cloudflarestatus.com ## Trigger / context Public status_incident report (FRESH_14D). ## Source evidence - https://www.cloudflarestatus.com/incidents/jg6ys8sbd6ny (2026-09-23T20:59:35.598Z) — evidence_cl
- OAuth client sends discovery/registration requests with no User-Agent, so WAF-fronted servers (Cloudflare) 403 the whole flow
Finding: In an external report against modelcontextprotocol/python-sdk (mcp 1.26.0, httpx 0.28.1, Python 3.11.13, Linux), the OAuth client's discovery and dynamic-registration requests reportedly carry no User-Agent header. A WAF-fronted MCP server such as one behind Cloudflare bot management may then return 403 for th
- wrangler deploy fails with authentication error 10000
## Problem - wrangler deploy fails with authentication error 10000 ## Observed symptom - `wrangler deploy` fails with Cloudflare API authentication error 10000 on the target account's Workers endpoint because the CLI login belongs to a different Cloudflare account and the project configuration pins no account_id. - Thi
Solutions with evidence
- Proposed fix: [Anthropic API] 413 request_too_large returned by Cloudflare before the API (32 MB Messages limit) — often from base64 images/PDFs
Recommended action: Reduce payload: upload large documents/images through the Files API and reference file_id, downscale images, or split the request. Option: Move large inputs to the Files API [evidence: official_recommended_action] Applies when: Large PDFs/images Steps: 1. Upload via Files API 2. Reference by file_id
- Researched guidance: What happens when one statement in a D1 batch transaction fails?
For Cloudflare D1's Worker Binding API, db.batch([...prepared statements]) is a single SQL transaction: statements execute sequentially and non-concurrently. If any statement fails, D1 returns an error for that statement and aborts/rolls back the entire batch, so writes made earlier in that same batch must not be treat
- Proposed fix: [Wrangler in CI/agent shell] 'In a non-interactive environment, it's necessary to set a CLOUDFLARE_API_TOKEN environment variable for wrangler to work'
Recommended action: Create a scoped API token and expose it to the Wrangler process as CLOUDFLARE_API_TOKEN (plus CLOUDFLARE_ACCOUNT_ID) via CI secrets; verify the secret actually reaches the step's environment. Option: Provide CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID as env [evidence: official_recommended_action
- Proposed fix: [Cloudflare Workers] 'Cannot perform I/O on behalf of a different request' when caching Request/Response/stream objects in global scope
Recommended action: Create I/O objects per request; cache plain data (not Response/stream objects), or use the Cache API/KV for cross-request caching. Option: Do not share I/O objects across requests [evidence: official_recommended_action] Applies when: Globals holding Response/stream/connection objects Steps: 1. Move