AI for developers
finish_reason, stop_reason and finishReason: What Each Value Means and What Your Code Should Do
In short
A finish_reason value is the only place an LLM API tells you why generation ended, and the three vendors name it differently: OpenAI finish_reason, Claude stop_reason, Gemini finishReason. Branch your handler on the situation, not the vendor word: cut off, tool wanted, refused, filtered, or clean end. Each API signals those situations with different values.
Where does each API put the reason, and what is it called?
Skipping this field is how a truncated JSON blob ends up in a database. The same fact is exposed under three names, in three places.
- OpenAI Chat Completions returns finish_reason on each choice, with the values stop, length, tool_calls, content_filter and the deprecated function_call.
- OpenAI's reasoning guide, which uses the Responses API, shows a different signal for a cut-off: a status of incomplete with an incomplete_details reason of max_output_tokens.
- Claude returns stop_reason on every successful Messages API response, and also a stop_sequence field and a stop_details field. Its values are end_turn, max_tokens, stop_sequence, tool_use, pause_turn, refusal and model_context_window_exceeded.
- Gemini returns finishReason on each candidate as a string enum. An empty value means the model has not stopped generating.
Which value tells you the answer was cut off?
OpenAI Chat Completions uses length when the token cap in the request was reached. In the Responses API the same event is an incomplete status, and the reasoning guide warns that it can arrive before any visible output because reasoning tokens use up the allowance.
Claude uses max_tokens for the cap and a separate model_context_window_exceeded when the response fills the model's context window, which the guide says to treat as truncated. That second value is typed only in the SDK's beta namespace, so a strict type check on the standard namespace will not list it.
Gemini uses MAX_TOKENS, and adds CONTINUATION for a response that hit the per-request limit with generation unfinished. A CONTINUATION response can be continued with the returned continuation_token, and the max_output_tokens count is cumulative across those calls.
Which value asks your code to do something next?
OpenAI signals a tool request with tool_calls, and the arguments arrive as a JSON string inside the message.
Claude has two values here. tool_use means Claude is calling a tool that you run, and you return the result. pause_turn means a server-side tool loop, such as web search, reached its iteration limit, which defaults to 10 for each request. For pause_turn you send the assistant content back unchanged to let the turn finish. The guide stresses that a tool you run always produces tool_use, never pause_turn.
Gemini's finishReason list has no plain tool-call value. What it does have are failure values around tools: MALFORMED_FUNCTION_CALL for an invalid call, UNEXPECTED_TOOL_CALL when no tools were enabled, TOO_MANY_TOOL_CALLS when the model called tools consecutively until the system exited, and MISSING_THOUGHT_SIGNATURE.
Which values mean a refusal or a filter?
OpenAI folds this into content_filter, meaning content was omitted after a flag from its content filters.
Claude uses refusal, and the guide says to read stop_details and retry on a fallback model. With structured outputs the status code stays 200, so a check on the HTTP code alone will miss it.
Gemini splits it into many values: SAFETY, RECITATION, LANGUAGE for an unsupported language, BLOCKLIST for forbidden terms, PROHIBITED_CONTENT, SPII for sensitive personal data, and an image group such as IMAGE_SAFETY and NO_IMAGE. Further values cover ESCALATION and an account limited under the prohibited use policy. A prompt can also be blocked before generation starts, which Gemini reports through a separate block reason rather than a finish reason.
When in a stream do you get the value?
On Claude, stop_reason is null in the initial message_start event, is provided in the message_delta event and appears in no other event. A streaming handler that records the value at the start will always record null.
Checked against: source 1
How would a vendor-neutral handler branch?
Map every vendor value onto a small set of outcomes, and make unknown values fail loudly instead of falling through to success.
| Outcome | OpenAI | Claude | Gemini |
|---|---|---|---|
| Clean end | stop | end_turn, stop_sequence | STOP |
| Output incomplete | length, or an incomplete status | max_tokens, model_context_window_exceeded | MAX_TOKENS, CONTINUATION |
| Run a tool | tool_calls | tool_use, pause_turn | No dedicated value in the list |
| Refused or filtered | content_filter | refusal | SAFETY, RECITATION, BLOCKLIST, PROHIBITED_CONTENT, SPII and others |
| Treat as an error | function_call is deprecated | A value your code does not know | MALFORMED_FUNCTION_CALL, UNEXPECTED_TOOL_CALL, TOO_MANY_TOOL_CALLS, MISSING_THOUGHT_SIGNATURE, OTHER |
What else do people ask?
Is finish_reason the same as an HTTP error?
No. Claude's guide separates the two: errors mean the request failed, while stop_reason explains why a successful response ended.
Can Claude return an empty answer with end_turn?
Yes. The guide says it can happen with end_turn, usually after tool results, when text is added right after a tool result block. Sending the tool result alone avoids it.
Sources
- Claude Platform docs, Stop reasons and fallback, fetched 2026-11-20
- OpenAI API reference, Create chat completion, fetched 2026-11-20
- OpenAI API docs, Reasoning models, fetched 2026-11-20
- Gemini API reference, generateContent, fetched 2026-11-20
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. This page compares the three vendors' documentation, which I read on 20 Nov 2026. I did not call any of the APIs to see these values appear, so it reports documented values, not observed ones. It does not cover Gemini's separate prompt-level block reasons beyond a mention, nor model-specific behaviour. Found a mistake? Tell me.