different-ai/openwork · warning

MCP_PROVIDER_HTTP_429

MCP_PROVIDER_HTTP_429

Error message

Wait for the provider rate limit to reset, then retry with bounded backoff.

What it means

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.

Source

Thrown at ee/apps/den-api/src/capability-sources/external-mcp-diagnostics.ts:1588

          code: "MCP_PROVIDER_INVALID_PARAMS",
          retryable: false,
          actionOwner: "openwork",
          operatorAction: "Correct the tool arguments using the latest advertised input schema; do not retry the same arguments unchanged.",
        }
      : providerPolicyDenied
      ? {
          phase: "PROVIDER_AUTHORIZATION",
          category: "provider_policy_denied",
          code: "MCP_PROVIDER_HTTP_403",
          retryable: false,
          actionOwner: "provider_admin",
          operatorAction: "Grant the provider role, ACL, or application permission required for this operation.",
        }
      : providerStatus === 429
        ? {
            phase: "PROVIDER_EXECUTION",
            category: "provider_throttled",
            code: "MCP_PROVIDER_HTTP_429",
            retryable: true,
            actionOwner: "provider_admin",
            operatorAction: "Wait for the provider rate limit to reset, then retry with bounded backoff.",
          }
        : {
            phase: "PROVIDER_EXECUTION",
            category: "provider_tool_error",
            code: "MCP_PROVIDER_TOOL_ERROR",
            retryable: false,
            actionOwner: "provider_admin",
            operatorAction: "Inspect the provider operation result and provider logs using the diagnostic reference.",
          }
    const classification: Classification = {
      ...classificationBase,
      ...(providerStatus === undefined ? {} : { providerStatus }),
      ...(providerCode ? { providerCode } : {}),
      payloadBytes: evidence.payloadBytes,
      ...(evidence.excerpt ? { providerErrorMessage: evidence.excerpt } : {}),

View on GitHub (pinned to 2b7df46e8a)

Solutions

1. Honor Retry-After and wait for the provider rate-limit window to reset before retrying.
2. Retry with bounded exponential backoff and jitter; cap attempts.
3. Serialize or throttle concurrent tool calls to stay under the provider quota.
4. Ask the provider admin for a higher quota or move to a tier with adequate limits.

Example fix

// before: immediate parallel fan-out
await Promise.all(ids.map((id) => callTool('get', { id })))
// after: paced with backoff on 429
for (const id of ids) { await callToolWithBackoff('get', { id }); await sleep(paceMs); }

const head = await fetch(apiBase + '/quota', { headers: { authorization: `Bearer ${token}` } });
const { remaining } = await head.json();
if (remaining <= 0) await waitForQuotaReset();

function isThrottled(d: { code: string }): boolean {
  return d.code === 'MCP_PROVIDER_HTTP_429';
}

try { return await callTool(name, args); } catch (e) {
  if (isThrottled(e.diagnostic)) return await backoffRetry(callTool, [name, args], { baseMs: 1000, capMs: 60000, respect: 'retry-after' });
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• MCP_HTTP_429
• MCP_OAUTH_TOO_MANY_REQUESTS
• MCP_PROVIDER_INVALID_PARAMS|MCP_PROVIDER_HTTP_403|MCP_PROVIDER_HTTP_429
• invalid_mcp_token_payload
• invalid_mcp_connection_payload

AI-assisted analysis of different-ai/openwork@2b7df46e8a (2026-09-01). Data as JSON: /api/errors/0f447045c48e38e1. Report an issue: GitHub.