When a tool-use request is malformed or targets an unsupported model, the Gateway returns a distinct code in the OpenAI-style error envelope so you can branch on it in your client. HTTP status is 400 unless noted.

Error envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "<one of the codes below>",
    "message": "Human-readable description of what went wrong.",
    "param": "tool_choice"
  }
}

Every error response also carries the request ID in the X-Request-ID header — include it when reporting issues.

Error codes

`tool_schema_invalid`

One of the tools[].function.parameters objects couldn't be parsed as a JSON Schema Draft 2020-12 object with type: "object" at the root. Also fires when tools[] exceeds 128 entries or a function.name doesn't match ^[a-zA-Z0-9_-]{1,64}$.

{
  "error": {
    "type": "invalid_request_error",
    "code": "tool_schema_invalid",
    "message": "tools[0].function.parameters.type must be 'object' at the root.",
    "param": "tools[0].function.parameters"
  }
}

Fix: validate your tool definitions locally against JSON Schema Draft 2020-12 before sending. See Provider compatibility → JSON Schema subset for which keywords are honoured per provider.

`tool_choice_invalid`

tool_choice references a function name that doesn't appear in the tools array, or uses a shape the Gateway doesn't recognize.

{
  "error": {
    "type": "invalid_request_error",
    "code": "tool_choice_invalid",
    "message": "tool_choice.function.name 'search_code' was not found in the tools array.",
    "param": "tool_choice"
  }
}

Fix: when forcing a specific function, make sure its name is in the tools[].function.name list:

{
  "tools": [{ "type": "function", "function": { "name": "search_code", ... } }],
  "tool_choice": { "type": "function", "function": { "name": "search_code" } }
}

`tool_call_id_mismatch`

A role: "tool" message carried a tool_call_id that wasn't emitted by the assistant earlier in the same request. Usually caused by out-of-order tool result messages in a multi-turn loop or a client that forgot to thread IDs through.

{
  "error": {
    "type": "invalid_request_error",
    "code": "tool_call_id_mismatch",
    "message": "messages[3].tool_call_id 'call_abc123' does not match any tool_call emitted in this request.",
    "param": "messages"
  }
}

Fix: keep the tool_call_id returned in each assistant tool_calls[].id and send it back verbatim on the matching role: "tool" message. The Gateway rewrites Anthropic's toolu_* IDs to call_* so clients see a stable shape across providers.

`tool_unsupported_for_model`

You requested tool use against a model that doesn't support it. The Gateway refuses explicitly rather than silently dropping the tools array — silent-drop leads to quietly broken apps.

{
  "error": {
    "type": "invalid_request_error",
    "code": "tool_unsupported_for_model",
    "message": "Model deepseek-reasoner does not support tool use. Use deepseek-chat or another model.",
    "param": "model"
  }
}

Fix: pick a model that supports tools for your request. The reasoning-style DeepSeek models (deepseek-reasoner, deepseek-r1) are the main case that hits this. See Provider compatibility → Reasoning models and tool use.

`tool_call_invalid_arguments`

With tools[].function.strict: true, the model emitted tool-call arguments that failed schema validation after the Gateway's internal retry. Only fires when strict is explicitly requested.

{
  "error": {
    "type": "invalid_request_error",
    "code": "tool_call_invalid_arguments",
    "message": "Tool call 'search_code' arguments failed schema validation: required field 'query' missing.",
    "param": "tools[0].function.strict"
  }
}

Fix: loosen the schema, drop strict: true, or switch to a provider that enforces schema server-side (OpenAI, Claude). The Gateway retries once before surfacing this error.

`tool_provider_error` (502)

Raised when the downstream provider fails during a tool-use request — usually a missing/invalid provider key, a 5xx from the upstream, or a hang during the tool-call phase. HTTP status is 502, not 400.

{
  "error": {
    "type": "invalid_request_error",
    "code": "tool_provider_error",
    "message": "No API key available for claude. Configure a platform key or supply a BYOK key.",
    "param": "model"
  }
}

Fix: check your BYOK configuration, verify the upstream provider's status page, and retry with a fallback array to cover flaky providers.

Retry guidance

Errors in this page are configuration errors (except tool_provider_error, which is transient). Retrying the same request with the same body will reproduce the error — fix the request, then retry.

Code	Retry safe?
`tool_schema_invalid`	❌ No — fix schema first
`tool_choice_invalid`	❌ No — fix `tool_choice` first
`tool_call_id_mismatch`	❌ No — fix message threading
`tool_unsupported_for_model`	❌ No — pick a different model
`tool_call_invalid_arguments`	⚠️ Maybe — already retried once by Gateway; further retries unlikely to help
`tool_provider_error`	✅ Yes — transient; use exponential backoff + `fallback`

Tool-Use Errors