OpenAI API 400: "Invalid parameter: messages with role 'tool' must be a response to a preceeding message with 'tool_calls'" (or 'tool_call_id ... not found'). What's wrong with my message history?

Cause: in Chat Completions, every message with role 'tool' must answer a tool call from the assistant message right before it. The assistant message must contain a tool_calls array, and each tool message's tool_call_id must match one of those calls. The error appears when that pairing breaks. Common reasons: - The assistant message that contained tool_calls was dropped, edited or re-created without its tool_calls (for example, only its text was saved to the database). - History was trimmed to fit the context window and the cut fell between the assistant message and its tool results. - Messages were stored and reloaded in the wrong order, or deduplicated. - A framework or proxy converted messages between formats and lost the tool_calls field. The opposite error ('An assistant message with tool_calls must be followed by tool messages responding to each tool_call_id') means a tool result is missing: every call in tool_calls needs its own tool message. How to check: print the final messages array right before the API call and confirm the pattern assistant (with tool_calls) followed by one tool message per call id, before the next user or assistant message. Fix: 1. Append the assistant message exactly as returned (including tool_calls), then one tool message per call with the matching tool_call_id, before calling the model again. If a tool fails, still send a tool message with an error result. 2. When trimming history, remove an assistant tool_calls message together with all of its tool results, never just one side. 3. When persisting chats, store the full message objects (role, content, tool_calls, tool_call_id), not just the text. 4. In LangChain / LangGraph, use the built-in message trimming that keeps tool call pairs together, and make sure AIMessage tool_calls survive serialization. After: add a small validation step that checks the pairing before every request, so a broken history fails fast with a clear message instead of a 400 mid-conversation. Sources: https://platform.openai.com/docs/guides/function-calling https://js.langchain.com/docs/troubleshooting/errors/INVALID_TOOL_RESULTS https://community.openai.com/t/new-api-changes-on-chat-completion-broke-some-previous-working-stuff/504311