Claude Platform Docs
PesanMembangun dengan Claude

Alasan berhenti dan fallback

Pelajari arti setiap nilai stop_reason dan cara menangani pemotongan, penggunaan alat, giliran yang dijeda, dan penolakan dalam aplikasi Anda.

Setiap respons Messages API menyertakan field stop_reasonPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. yang memberi tahu Anda mengapa Claude berhenti menghasilkan output. Periksa field ini untuk memutuskan apakah akan menggunakan respons apa adanya, melanjutkan percakapan, mencoba ulang, atau beralih (fallback) ke model lain.

Untuk skema respons lengkap, lihat referensi Messages APIPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali..

Referensi cepat

NilaiKapan terjadiApa yang harus dilakukan
end_turnClaude menyelesaikan responsnya secara alami.Gunakan responsnya.
max_tokensRespons mencapai batas max_tokens Anda.Naikkan max_tokens atau lanjutkan respons.
stop_sequenceClaude mengeluarkan salah satu stop_sequences Anda.Baca stop_sequence untuk melihat mana yang terpicu.
tool_useClaude sedang memanggil alat.Jalankan alat dan kembalikan hasilnya. Panggilan alat server yang masih belum memiliki blok hasilnya akan selesai dalam respons berikutnya.
pause_turnLoop alat server mencapai batas iterasinya.Kirim kembali konten asisten untuk melanjutkan.
refusalClaude menolak untuk merespons.Baca stop_details dan coba ulang pada model fallback.
model_context_window_exceededRespons memenuhi jendela konteks model.Perlakukan respons sebagai terpotong.

Field stop_reason

Field stop_reason adalah bagian dari setiap respons Messages API yang berhasil. Tidak seperti error, yang menunjukkan kegagalan dalam memproses permintaan Anda, stop_reason memberi tahu Anda mengapa Claude menyelesaikan pembuatan responsnya.

Example response
{
  "id": "msg_01234",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here's the answer to your question..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "stop_details": null,
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50
  }
}

Nilai alasan berhenti

end_turn

Alasan berhenti yang paling umum. Menunjukkan bahwa Claude menyelesaikan responsnya secara alami.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
if response.stop_reason == "end_turn":
    # Proses respons lengkap
    for block in response.content:
        if block.type == "text":
            print(block.text)

max_tokens

Claude berhenti karena mencapai batas max_tokensPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. yang ditentukan dalam permintaan Anda.

client = anthropic.Anthropic()
# Permintaan dengan token terbatas
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=10,
    messages=[{"role": "user", "content": "Explain quantum physics"}],
)

if response.stop_reason == "max_tokens":
    # Respons terpotong
    print("Response was cut off at token limit")
    # Pertimbangkan untuk membuat permintaan lain agar dapat melanjutkan

stop_sequence

Claude menemukan salah satu stop sequencePratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. kustom Anda.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    stop_sequences=["END", "STOP"],
    messages=[{"role": "user", "content": "Generate text until you say END"}],
)

if response.stop_reason == "stop_sequence":
    print(f"Stopped at sequence: {response.stop_sequence}")

tool_use

Claude sedang memanggil alat yang perlu Anda jalankan.

client = anthropic.Anthropic()
weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "City and state"},
        },
        "required": ["location"],
    },
}


def execute_tool(name, tool_input):
    """Run a tool and return the result."""
    return f"Weather in {tool_input.get('location', 'unknown')}: 72°F"


response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
)

if response.stop_reason == "tool_use":
    # Ekstrak dan jalankan alat
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            # Kembalikan hasil ke Claude untuk respons akhir

Ketika alat server masih menunggu

Claude dapat memanggil sebuah alat server dan alat klien (alat yang dijalankan oleh kode Anda) dalam kelompok panggilan alat paralel yang sama. API kemudian mengembalikan respons tool_use tanpa menjalankan alat server agar Anda dapat menjalankan alat klien terlebih dahulu.

Panggilan yang menunggu adalah blok server_tool_use atau mcp_tool_use tanpa blok hasil. Tidak ada hal lain dalam respons yang menandainya. Setelah alat server berjalan, blok hasilnya, seperti web_search_tool_result, menyimpan id panggilan tersebut di field tool_use_id-nya.

Respons campuran ini memiliki alat server yang sedang menunggu dan panggilan alat klien:

A mixed tool_use response
{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "name": "web_search",
      "input": { "query": "example article" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "name": "run_command",
      "input": { "command": "uname -a" }
    }
  ]
}

Untuk melanjutkan dari respons campuran seperti ini, buat permintaan lanjutan:

  1. Pertahankan pesan-pesan sebelumnya dan tambahkan content respons tanpa diubah sebagai pesan assistant.
  2. Tambahkan pesan pengguna yang hanya berisi blok tool_result, satu untuk setiap blok tool_use klien. Panggilan yang menunggu tidak mendapatkannya.
  3. Kirim permintaan dengan array tools yang sama seperti sebelumnya agar alat server yang menunggu tetap terdefinisi.

Untuk field-field blok tool_result, lihat Menangani panggilan alat. Pesan pengguna dalam permintaan lanjutan terlihat seperti ini:

The follow-up user message
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
    }
  ]
}

API menambahkan hasil Anda ke giliran Claude yang belum selesai, menjalankan alat server yang menunggu, dan melanjutkan. Untuk alat server yang dipanggil Claude secara langsung, content respons berikutnya dimulai dengan blok hasil alat tersebut.

Loop yang mengikuti langkah-langkah sebelumnya untuk setiap respons tool_use tidak perlu mendeteksi alat server yang menunggu. Pada permintaan berikutnya, pertahankan tiga pesan terpisah di messages, dengan urutan berikut: respons pertama, pesan tool_result Anda, dan respons berikutnya.

Dua kasus memerlukan satu field tambahan dalam permintaan lanjutan:

  • Respons menyertakan container: Kirimkan kembali ID-nya (lihat bagian Penggunaan ulang container pada alat eksekusi kode).
  • Blok yang menunggu adalah blok mcp_tool_use: Kirim mcp_servers yang sama seperti sebelumnya.

Setiap kesalahan berikut dalam permintaan lanjutan akan gagal dengan 400 invalid_request_error. Pesan yang ditampilkan adalah untuk pencarian web. Untuk alat server lainnya, nama-nama di dalamnya berbeda.

KesalahanPesan error mencakup
tools tidak lagi mendefinisikan alat server yang menunggubut no `web_search` tool was provided
Teks atau konten lain muncul setelah blok tool_resultwas found without a corresponding `web_search_tool_result` block
Dengan pemanggilan alat terprogram, teks atau konten lain muncul setelah blok tool_resultonly tool_result blocks are allowed
Teks atau konten lain muncul sebelum blok tool_result`tool_use` ids were found without `tool_result` blocks immediately after
Sebuah blok tool_result hilang`tool_use` ids were found without `tool_result` blocks immediately after

Konten setelah blok tool_result akan gagal karena mengakhiri giliran Claude saat alat server masih menunggu. Untuk memberi Claude input tambahan, lanjutkan hingga stop_reason sebuah respons bukan tool_use maupun pause_turn. Kemudian, kirimkan input tersebut sebagai pesan pengguna baru dalam daftar messages yang sama.

pause_turn

Dikembalikan ketika loop sampling sisi server mencapai batas iterasinya saat menjalankan server tool seperti pencarian web. Batas default adalah 10 iterasi untuk setiap permintaan.

Ketika Claude berhenti untuk memanggil alat yang Anda jalankan, alasan berhentinya adalah tool_use, tidak pernah pause_turn.

Agar Claude dapat menyelesaikan giliran yang dijeda, buat permintaan baru:

  1. Pertahankan pesan-pesan sebelumnya dan tambahkan content respons tanpa diubah sebagai pesan assistant, termasuk blok server_tool_use apa pun yang tidak memiliki blok hasil.
  2. Kirim permintaan dengan tools yang sama seperti sebelumnya dan tanpa pesan pengguna setelah pesan assistant.

Jika respons menyertakan container, kirimkan juga ID-nya kembali agar giliran tersebut mempertahankan file-filenya. Untuk detailnya, lihat bagian Penggunaan ulang container pada alat eksekusi kode. Contoh-contoh berikut menggunakan pencarian web dan tidak mengirimkan ID container:

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    messages=[{"role": "user", "content": "Search for latest AI news"}],
)

if response.stop_reason == "pause_turn":
    # Lanjutkan percakapan dengan mengirimkan kembali respons tersebut
    messages = [
        {"role": "user", "content": "Search for latest AI news"},
        {"role": "assistant", "content": response.content},
    ]
    continuation = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search"}],
    )

Aplikasi Anda harus menangani pause_turn dalam setiap loop agen yang menggunakan alat server. Untuk loop yang menangani jeda berulang dan mengirimkan kembali ID container, lihat Implementasikan logika percobaan ulang untuk pause_turn.

refusal

Claude menolak untuk menghasilkan respons. Pengklasifikasi keamanan mengembalikan alasan berhenti ini sebagai respons HTTP 200 normal, bukan error.

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "[Unsafe request]"}],
)

if response.stop_reason == "refusal":
    # Claude menolak untuk merespons
    print("Claude was unable to process this request")
    # Pertimbangkan untuk menyusun ulang atau mengubah permintaan

Pada penolakan, objek stop_detailsPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. mengidentifikasi kategori kebijakan yang memicunya. Kategori-kategori tersebut dan bentuk lengkap respons penolakan dibahas dalam Seperti apa penolakan itu. stop_details bernilai null untuk semua alasan berhenti selain refusal.

Anda biasanya dapat memperoleh respons atas permintaan yang ditolak dengan mencoba ulang pada model Claude lain. Cara ini berlaku untuk Claude Fable 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, dan Claude Haiku 5.5. Penolakan dan fallback menunjukkan cara menyiapkan percobaan ulang tersebut, di sisi server atau di klien Anda. Claude Haiku 5.5 tidak memiliki fallback sisi server, jadi siapkan percobaan ulangnya dengan fallback sisi klien. Jika Anda membangun sendiri percobaan ulang dari salah satu model ini kecuali Claude Haiku 5.5, Kredit fallback menjelaskan cara menghindari membayar biaya cache prompt dua kali.

model_context_window_exceeded

Claude berhenti karena mencapai batas “context window” (jendela konteks) model. Ini memungkinkan Anda meminta token maksimum yang mungkin tanpa mengetahui ukuran input yang tepat.

client = anthropic.Anthropic()

# Permintaan dengan token maksimum untuk mendapatkan hasil sebanyak mungkin
response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k
    messages=[
        {"role": "user", "content": "Large input that uses most of context window..."}
    ],
)

if response.stop_reason == "model_context_window_exceeded":
    # Respons mencapai batas jendela konteks sebelum max_tokens
    print("Response reached model's context window limit")
    # Respons tetap valid tetapi dibatasi oleh jendela konteks

Praktik terbaik untuk menangani alasan berhenti

Selalu periksa stop_reason

Biasakan untuk memeriksa stop_reason dalam logika penanganan respons Anda:

def handle_response(response):
    match response.stop_reason:
        case "tool_use":
            return handle_tool_use(response)
        case "max_tokens":
            return handle_truncation(response)
        case "model_context_window_exceeded":
            return handle_context_limit(response)
        case "pause_turn":
            return handle_pause(response)
        case "refusal":
            return handle_refusal(response)
        case _:
            # Tangani end_turn dan kasus lainnya
            return next(
                (block.text for block in response.content if block.type == "text"),
                "",
            )

Tangani respons terpotong dengan baik

Ketika respons terpotong karena batas token atau jendela konteks, tambahkan pemberitahuan agar pembaca tahu bahwa output tidak lengkap. Untuk melanjutkan pembuatan dari titik respons terhenti, lihat Memastikan respons lengkap.

def handle_truncated_response(response):
    text = next((block.text for block in response.content if block.type == "text"), "")
    if response.stop_reason in ["max_tokens", "model_context_window_exceeded"]:
        if response.stop_reason == "max_tokens":
            note = "[Response truncated due to max_tokens limit]"
        else:
            note = "[Response truncated due to context window limit]"
        return f"{text}\n\n{note}"
    return text

Implementasikan logika percobaan ulang untuk pause_turn

Ketika Anda menggunakan server tool, API mungkin mengembalikan pause_turn jika loop sampling sisi server mencapai batas iterasinya (default 10). Tangani hal ini dengan menambahkan respons yang dijeda ke pesan Anda tanpa diubah, lalu kirim permintaan tersebut lagi. Jika respons menyertakan container, kirimkan juga ID-nya kembali. Tanpa ID tersebut, permintaan berikutnya akan memulai container baru, dan file dari bagian mana pun dalam giliran tersebut sebelum jeda akan hilang.

client = anthropic.Anthropic()


def handle_server_tool_conversation(client, user_query, tools, max_requests=5):
    messages = [{"role": "user", "content": user_query}]
    container_id = None

    for _ in range(max_requests):
        response = client.messages.create(
            model="claude-opus-5-5",
            max_tokens=4096,
            messages=messages,
            tools=tools,
            container=container_id,
        )

        if response.stop_reason != "pause_turn":
            # Tidak dijeda: kembalikan respons
            return response

        # pause_turn: tambahkan respons yang dijeda sebagai pesan assistant, lalu lanjutkan
        messages.append({"role": "assistant", "content": response.content})

        # Jika alat berjalan di container, kirim kembali ID-nya agar file-nya tetap tersimpan
        if response.container:
            container_id = response.container.id

    # Masih dijeda setelah max_requests permintaan: kembalikan respons terakhir
    return response


response = handle_server_tool_conversation(
    client,
    "Use the code execution tool to find the 1,000th prime number.",
    [{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response.stop_reason)

Fungsi ini mengembalikan respons terakhir, yang hanya memuat bagian akhir dari giliran tersebut. Untuk menampilkan seluruh giliran atau untuk melanjutkan percakapan, simpan juga respons-respons yang dijeda.

Alasan berhenti vs. error

Penting untuk membedakan antara nilai stop_reason dan error yang sebenarnya:

Alasan berhenti (respons berhasil)

  • Bagian dari body respons
  • Menunjukkan mengapa pembuatan berhenti secara normal
  • Respons berisi konten yang valid

Error (permintaan gagal)

  • Kode status HTTP 4xx atau 5xx
  • Menunjukkan kegagalan pemrosesan permintaan
  • Respons berisi detail error
client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello!"}],
    )

    # Tangani respons yang berhasil dengan stop_reason
    if response.stop_reason == "max_tokens":
        print("Response was truncated")

except anthropic.APIStatusError as e:
    # Tangani error yang sebenarnya
    match e.status_code:
        case 429:
            print("Rate limit exceeded")
        case 500:
            print("Server error")

Pertimbangan streaming

Saat menggunakan streaming, stop_reason:

  • Bernilai null dalam event message_start awal
  • Disediakan dalam event message_delta
  • Tidak disediakan dalam event lainnya
client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
) as stream:
    for event in stream:
        if event.type == "message_delta":
            stop_reason = event.delta.stop_reason
            if stop_reason:
                print(f"Stream ended with: {stop_reason}")

Pola umum

Menangani alur kerja penggunaan alat

def complete_tool_workflow(client, user_query, tools):
    messages = [{"role": "user", "content": user_query}]

    while True:
        response = client.messages.create(
            model="claude-opus-5-5",
            max_tokens=1024,
            messages=messages,
            tools=tools,
        )

        if response.stop_reason == "tool_use":
            # Jalankan alat dan lanjutkan
            tool_results = execute_tools(response.content)
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})
        else:
            # Respons akhir
            return response

Memastikan respons lengkap

def get_complete_response(client, prompt, max_attempts=3):
    messages = [{"role": "user", "content": prompt}]
    full_response = ""

    for _ in range(max_attempts):
        response = client.messages.create(
            model="claude-opus-5-5", messages=messages, max_tokens=4096
        )

        full_response += next(
            (block.text for block in response.content if block.type == "text"), ""
        )

        if response.stop_reason != "max_tokens":
            break

        # Lanjutkan dari titik terakhir berhenti
        messages = [
            {"role": "user", "content": prompt},
            {"role": "assistant", "content": full_response},
            {"role": "user", "content": "Please continue from where you left off."},
        ]

    return full_response

Mendapatkan token maksimum tanpa mengetahui ukuran input

Dengan alasan berhenti model_context_window_exceeded, Anda dapat meminta token maksimum yang mungkin tanpa menghitung ukuran input:

def get_max_possible_tokens(client, prompt):
    """
    Get as many tokens as possible within the model's context window
    without needing to calculate input token count
    """
    response = client.beta.messages.create(
        model="claude-opus-5-5",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=20000,  # Python SDK requires streaming for max_tokens above ~21k
    )

    match response.stop_reason:
        case "model_context_window_exceeded":
            # Mendapat token maksimum yang dimungkinkan sesuai ukuran input
            print(
                f"Generated {response.usage.output_tokens} tokens (context limit reached)"
            )
        case "max_tokens":
            # Mendapat token tepat sebanyak yang diminta
            print(
                f"Generated {response.usage.output_tokens} tokens (max_tokens reached)"
            )
        case _:
            # Penyelesaian alami
            print(
                f"Generated {response.usage.output_tokens} tokens (natural completion)"
            )

    return next((block.text for block in response.content if block.type == "text"), "")

Langkah selanjutnya

Coba ulang permintaan yang ditolak pada model fallback, di sisi server atau di klien Anda.

Biarkan SDK mengelola loop tool_use, pemformatan hasil, dan percobaan ulang untuk Anda.

Baca stop_reason dari event message_delta saat streaming.

Tangani error HTTP 4xx dan 5xx, yang berbeda dari alasan berhenti.

Apakah halaman ini membantu?