Crédit de repli

Les caches de prompts sont propres à chaque modèle. Lorsque Claude Fable 5 refuse une requête et que vous réessayez sur un autre modèle, le préfixe de conversation qui était déjà mis en cache pour Claude Fable 5 doit être écrit de zéro dans le cache du nouveau modèle, et les écritures de cache coûtent plus cher que les lectures de cache. Le « fallback credit » (crédit de repli) élimine ce coût supplémentaire : le refus contient un jeton de crédit, vous renvoyez ce jeton lors de la nouvelle tentative, et celle-ci est facturée comme si la conversation s'était déroulée sur le nouveau modèle depuis le début.

Vous n'avez besoin de cette page que si vous construisez vous-même la nouvelle tentative : avec le SDK Ruby ou PHP, via HTTP brut, ou avec une logique de nouvelle tentative personnalisée. Le repli côté serveur et le middleware du SDK appliquent automatiquement le crédit de repli. Si vous utilisez l'un ou l'autre, ignorez cette page.

La page Refus et repli explique comment détecter les refus et choisir une approche de repli. La page Mise en cache des prompts explique les lectures et écritures de cache si ces termes vous sont nouveaux.

Le flux de base

Le champ fallback_has_prefill_claim vous indique si la nouvelle tentative peut poursuivre la sortie partielle du modèle refusé au lieu de recommencer :

Exemple

L'exemple ci-dessous effectue une requête susceptible d'être refusée, utilise le jeton de crédit lors d'une nouvelle tentative sur Claude Opus 4.8, et se dégrade en suivant l'échelle de rejet décrite dans Lorsqu'une nouvelle tentative est rejetée.

client = Anthropic()

request = {
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}],
}


def send(model, body):
    return client.beta.messages.create(
        model=model, betas=["fallback-credit-2026-06-01"], **body
    )


response = send("claude-fable-5", request)

if (
    response.stop_reason == "refusal"
    and (details := response.stop_details)
    and (token := details.fallback_credit_token)
):
    exact_body = request | {"fallback_credit_token": token}
    # Préférer la forme de continuation sauf si l'assertion est False
    if details.fallback_has_prefill_claim is not False:
        # Reprendre le contenu du refus, en supprimant les espaces finaux d'un
        # dernier bloc de texte (le validateur de préremplissage le rejette ; la
        # correspondance côté serveur tolère la modification). Les requêtes avec outils omettent aussi
        # les blocs tool_use non appariés, puis resuppriment les espaces après toute omission.
        echoed = [block.model_dump() for block in response.content]
        match echoed:
            case [*_, {"type": "text"} as final_block]:
                final_block["text"] = final_block["text"].rstrip()
        attempt = exact_body | {
            "messages": [
                *request["messages"],
                {"role": "assistant", "content": echoed},
            ]
        }
    else:
        attempt = exact_body

    try:
        response = send("claude-opus-4-8", attempt)
    except BadRequestError as error:
        if "redemption temporarily unavailable" in str(error):
            raise  # Transient: retry with the token within its five-minute window
        try:
            # Revenir au corps inchangé, toujours avec le jeton
            response = send("claude-opus-4-8", exact_body)
        except BadRequestError as error:
            if "redemption temporarily unavailable" in str(error):
                raise  # Transient: retry with the token within its five-minute window
            # Le jeton lui-même a été rejeté : l'abandonner et réessayer sans.
            response = send("claude-opus-4-8", request)

print(json.dumps({"stop_reason": response.stop_reason, "model": response.model}))

Où cela fonctionne

Le crédit de repli est en bêta sur l'API Claude, Claude Platform sur AWS, Amazon Bedrock, Vertex AI et Microsoft Foundry. Les jetons de crédit renvoyés dans les résultats de Message Batches ne peuvent pas être utilisés ; l'utilisation s'applique uniquement aux requêtes directes de l'API Messages.

Le modèle de la nouvelle tentative doit être l'une des cibles de repli autorisées du modèle refusé. Au lancement, la cible autorisée de Claude Fable 5 est Claude Opus 4.8 (claude-opus-4-8).

Vérifier que le crédit a été appliqué

Le remboursement est visible dans le usage de la nouvelle tentative : cache_creation_input_tokens est plus bas, et cache_read_input_tokens est plus élevé du même montant, par rapport à ce que la même requête indiquerait sans le jeton. Un écart de zéro signifie que le jeton a été honoré mais qu'il n'y avait rien à retarifer, par exemple parce que le cache du modèle de la nouvelle tentative était déjà chaud.

Lorsqu'une nouvelle tentative est rejetée

La plupart des nouvelles tentatives aboutissent dès le premier essai. Lorsque ce n'est pas le cas, l'API renvoie une erreur 400 qui vous indique quoi essayer ensuite.

Référence

Les sections ci-dessous couvrent les cas limites et les règles complètes d'utilisation du crédit. La plupart des intégrations n'en ont pas besoin.

Étapes suivantes