Claude API Function Calling Error Retries: A Fix Guide

When Claude's function calling (tool use) fails mid-request — a malformed tool_use block, an invalid JSON argument, a tool that returns an error, or a request that times out before the model finishes reasoning — the fix is almost never "just retry the whole request." You need to distinguish retryable errors (rate limits, 5xx, network timeouts) from non-retryable errors (bad tool schema, invalid arguments the model keeps generating the same way), and you need to feed tool errors back into the conversation instead of discarding them.

This article covers the actual error types you'll hit with Claude's tool use API, how to build a retry loop that doesn't waste tokens or loop forever, and where a proxy layer like SubToAPI can absorb some of this complexity for you.

Why function calling fails

Tool use with Claude involves three moving parts: the model deciding to call a tool, generating arguments for it, and your code executing that tool and returning a result. Errors can happen at any of these steps:

• Schema mismatch — the model generates arguments that don't match your tool's input_schema (wrong type, missing required field, extra field it invented).
• Invalid JSON — rare with Claude but can happen with very long or nested argument objects, especially under aggressive max_tokens limits that cut a response short.
• Tool execution failure — your own function throws (API down, database timeout, permission denied).
• HTTP-level errors — 429 rate limits, 500/503 server errors, connection timeouts.
• stop_reason: max_tokens during a tool call, which truncates the tool_use block before it's valid JSON.

The first two and the last one are model-generation problems. The third is your infrastructure. The fourth is transport. Each needs a different retry strategy.

Retryable vs non-retryable errors

Treat these separately, or your retry loop will burn through requests retrying things that will never succeed:

Retryable (transport-level):

• HTTP 429 (rate limited)
• HTTP 500/502/503/504
• Connection reset / timeout
• overloaded_error from the API

Not retryable by resending the same request — needs a corrected request:

• Truncated tool_use JSON due to max_tokens
• Model-generated arguments that fail your schema validation
• Your own tool function throwing an error that the model needs to see and react to

For the second category, the fix is to send the error back to Claude as a tool result and let it try again with context, not to blindly resubmit the same prompt.

A retry pattern that actually works

Here's a pattern combining exponential backoff for transport errors with a feedback loop for tool errors:

async function callWithRetry(client, params, { maxRetries = 3 } = {}) {
  let attempt = 0;
  while (true) {
    try {
      const response = await client.messages.create(params);
      return response;
    } catch (err) {
      attempt++;
      const retryable = [429, 500, 502, 503, 504].includes(err.status);
      if (!retryable || attempt > maxRetries) throw err;

      const delay = Math.min(1000 * 2 ** attempt, 15000) + Math.random() * 500;
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

That handles transport-level failures. For tool-level failures, feed the error back as a tool_result with is_error: true so Claude can self-correct:

async function runToolLoop(client, messages, tools) {
  let response = await callWithRetry(client, { model: "claude-opus-4", max_tokens: 1024, tools, messages });

  while (response.stop_reason === "tool_use") {
    const toolUse = response.content.find(c => c.type === "tool_use");
    let result;
    try {
      result = await executeTool(toolUse.name, toolUse.input);
    } catch (err) {
      result = { error: err.message };
    }

    messages.push({ role: "assistant", content: response.content });
    messages.push({
      role: "user",
      content: [{
        type: "tool_result",
        tool_use_id: toolUse.id,
        content: JSON.stringify(result),
        is_error: !!result.error,
      }],
    });

    response = await callWithRetry(client, { model: "claude-opus-4", max_tokens: 1024, tools, messages });
  }
  return response;
}

The key detail is is_error: true — Claude uses that flag to understand the previous attempt failed and will often adjust its next call (different arguments, a fallback tool, or an explanation to the user) rather than repeating the identical broken call.

Handling truncated tool_use blocks

If stop_reason comes back as max_tokens while the model was mid-tool_use, the JSON in that block is likely incomplete and will fail to parse. Don't try to repair truncated JSON — increase max_tokens and resend the same conversation up to that point. This is a legitimate case for a plain retry, not a tool-error feedback loop, since the model never finished generating a valid call.

if (response.stop_reason === "max_tokens") {
  response = await callWithRetry(client, {
    ...params,
    max_tokens: params.max_tokens * 2,
  });
}

Validate before you execute

A cheap way to cut error volume in half: validate tool_use.input against your JSON schema locally before calling your tool function. If validation fails, skip execution entirely and send is_error: true with a clear message about which field was wrong — this gives Claude a much more useful signal than a stack trace from your backend, and it avoids side effects from partially-valid calls (e.g., calling a payment API with a missing currency field).

Where SubToAPI fits

If you're running Claude through a subscription-backed proxy like SubToAPI instead of calling Anthropic directly, the same retry logic above applies unchanged — SubToAPI exposes the standard Messages format with tool_use/tool_result blocks, so your loop doesn't need to know which backend it's talking to. What it does add is a consistent surface for rate limits and usage metadata across team seats, which makes it easier to tell "this is a 429 I should back off on" from "this is a tool schema bug I need to fix in code," since every key on the dashboard reports errors the same way regardless of which teammate or app triggered them.

See the tool use docs for the exact request/response shape, streaming docs if you're combining tool calls with streamed output, and the quickstart to get a key. Plans start with a free trial at signup; pricing is at /pricing.

Practical checklist

• Separate transport retries (backoff) from tool-error retries (feedback loop)
• Always validate tool arguments locally before executing side-effecting code
• Use is_error: true on tool_result so Claude adjusts instead of repeating
• Treat max_tokens truncation of a tool_use block as a "raise the limit and resend" case, not a JSON repair job
• Cap total retries per conversation turn — 3 is usually enough before falling back to a human-readable error message for the user

questions

Why does Claude generate invalid arguments for my tool? Usually the input_schema is ambiguous or the tool description doesn't explain constraints (e.g., date format, enum values). Tightening the schema and adding examples in the tool description reduces this far more than retry logic can.

Should I retry on every non-200 response? No. Only retry 429 and 5xx-class errors with backoff. 400-class errors (invalid request, bad schema) indicate a request problem that retrying won't fix — you need to correct the payload first.

How many retries is reasonable for a tool call loop? Two to three attempts per tool call is typical. Beyond that, the model is usually stuck on a real ambiguity in the tool definition or the underlying data, and looping further just wastes tokens without improving the outcome.