{"record":{"id":"0f447045c48e38e1","repo":"different-ai/openwork","slug":"mcp-provider-http-429","errorCode":"MCP_PROVIDER_HTTP_429","errorMessage":"Wait for the provider rate limit to reset, then retry with bounded backoff.","messagePattern":"Wait for the provider rate limit to reset, then retry with bounded backoff\\.","errorType":"error_code","errorClass":null,"httpStatus":429,"severity":"warning","filePath":"ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts","lineNumber":1588,"sourceCode":"          code: \"MCP_PROVIDER_INVALID_PARAMS\",\n          retryable: false,\n          actionOwner: \"openwork\",\n          operatorAction: \"Correct the tool arguments using the latest advertised input schema; do not retry the same arguments unchanged.\",\n        }\n      : providerPolicyDenied\n      ? {\n          phase: \"PROVIDER_AUTHORIZATION\",\n          category: \"provider_policy_denied\",\n          code: \"MCP_PROVIDER_HTTP_403\",\n          retryable: false,\n          actionOwner: \"provider_admin\",\n          operatorAction: \"Grant the provider role, ACL, or application permission required for this operation.\",\n        }\n      : providerStatus === 429\n        ? {\n            phase: \"PROVIDER_EXECUTION\",\n            category: \"provider_throttled\",\n            code: \"MCP_PROVIDER_HTTP_429\",\n            retryable: true,\n            actionOwner: \"provider_admin\",\n            operatorAction: \"Wait for the provider rate limit to reset, then retry with bounded backoff.\",\n          }\n        : {\n            phase: \"PROVIDER_EXECUTION\",\n            category: \"provider_tool_error\",\n            code: \"MCP_PROVIDER_TOOL_ERROR\",\n            retryable: false,\n            actionOwner: \"provider_admin\",\n            operatorAction: \"Inspect the provider operation result and provider logs using the diagnostic reference.\",\n          }\n    const classification: Classification = {\n      ...classificationBase,\n      ...(providerStatus === undefined ? {} : { providerStatus }),\n      ...(providerCode ? { providerCode } : {}),\n      payloadBytes: evidence.payloadBytes,\n      ...(evidence.excerpt ? { providerErrorMessage: evidence.excerpt } : {}),","sourceCodeStart":1570,"sourceCodeEnd":1606,"githubUrl":"https://github.com/different-ai/openwork/blob/2b7df46e8ae1517d64c896c7793d2d52ec845669/ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts#L1570-L1606","documentation":"This diagnostic code classifies a tool call failure where the provider returned HTTP 429: the classifier emits provider_throttled at phase PROVIDER_EXECUTION, retryable true. The external MCP provider's backing API is rate-limiting requests. Ownership is assigned to the provider admin (quota owner), and the operator action is to wait for reset and retry with bounded backoff.","triggerScenarios":"An MCP tool invocation whose upstream HTTP response status is 429: exceeding the provider's per-token/per-IP quota, burst parallel tool calls from an agent loop, shared egress IP hitting provider limits, or provider-side throttling during peak load.","commonSituations":"Agent executing many tool calls in rapid succession without pacing; multiple users behind one NAT/proxy IP sharing a quota; free-tier provider quotas; recently lowered provider rate limits; nightly batch jobs colliding with interactive use.","solutions":["Honor Retry-After and wait for the provider rate-limit window to reset before retrying.","Retry with bounded exponential backoff and jitter; cap attempts.","Serialize or throttle concurrent tool calls to stay under the provider quota.","Ask the provider admin for a higher quota or move to a tier with adequate limits."],"exampleFix":"// before: immediate parallel fan-out\nawait Promise.all(ids.map((id) => callTool('get', { id })))\n// after: paced with backoff on 429\nfor (const id of ids) { await callToolWithBackoff('get', { id }); await sleep(paceMs); }","handlingStrategy":"retry","validationCode":"const head = await fetch(apiBase + '/quota', { headers: { authorization: `Bearer ${token}` } });\nconst { remaining } = await head.json();\nif (remaining <= 0) await waitForQuotaReset();","typeGuard":"function isThrottled(d: { code: string }): boolean {\n  return d.code === 'MCP_PROVIDER_HTTP_429';\n}","tryCatchPattern":"try { return await callTool(name, args); } catch (e) {\n  if (isThrottled(e.diagnostic)) return await backoffRetry(callTool, [name, args], { baseMs: 1000, capMs: 60000, respect: 'retry-after' });\n  throw e;\n}","preventionTips":["Throttle/queue tool calls to stay under the provider quota","Honor Retry-After headers and never tight-loop on 429","Distribute load across tokens/IPs when legitimately possible","Alert on quota-consumption trends before limits are hit"],"tags":["mcp","http-429","rate-limit","retry"],"backgroundTag":"rate-limit-exceeded","analyzedSha":"2b7df46e8ae1517d64c896c7793d2d52ec845669","analyzedAt":"2026-09-01T07:59:23.713Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}