Crédit de repli

Les caches de prompts sont propres à chaque modèle. Lorsque Claude Fable 5 décline 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. Les écritures en cache coûtent plus cher que les lectures en cache. Le « fallback credit » (crédit de repli) supprime ce coût supplémentaire. Le refus porte 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 depuis le début sur le nouveau modèle.

Vous n'avez besoin de cette page que lorsque vous construisez la nouvelle tentative vous-même : en 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.

Refus et repli couvre la détection des refus et le choix d'une approche de repli. Mise en cache des prompts explique les lectures et écritures en cache si ces termes sont nouveaux pour vous.



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 repartir de zéro :



Exemple

L'exemple suivant effectue une requête susceptible d'être refusée et échange le jeton de crédit lors d'une nouvelle tentative sur Claude Opus 4.8. Lorsqu'une tentative est rejetée, l'exemple descend l'échelle de rejet : la séquence de formes de nouvelle tentative progressivement plus simples décrite dans Quand une nouvelle tentative est rejetée.

client = Anthropic()

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


def send(model: str, body: dict[str, object]) -> BetaMessage:
    return client.beta.messages.create(
        model=model, betas=["fallback-credit-2026-07-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}
    # Privilégier la forme de continuation sauf si la revendication est False
    if details.fallback_has_prefill_claim is not False:
        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 error.message:
            raise  # Transient: retry with the token within its five-minute window
        try:
            # Se rabattre sur le corps inchangé, toujours avec le jeton
            response = send("claude-opus-4-8", exact_body)
        except BadRequestError as retry_error:
            if "redemption temporarily unavailable" in retry_error.message:
                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, Amazon Bedrock, Claude Platform sur AWS, Google Cloud et Microsoft Foundry. Les refus dans les Message Batches ne génèrent pas de jetons de crédit, et l'échange ne s'applique qu'aux requêtes directes de l'API Messages : un jeton transmis dans une requête de lot est accepté mais ignoré.

Le modèle de la nouvelle tentative doit être l'une des cibles de repli autorisées du modèle refusé. Les cibles autorisées de Claude Fable 5 sont Claude Opus 4.8 (claude-opus-4-8) et Claude Opus 5 (claude-opus-5).



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

Le remboursement est visible dans le champ usage de la nouvelle tentative. Par rapport à ce que la même requête rapporterait sans le jeton, cache_creation_input_tokens est plus bas, et cache_read_input_tokens est plus élevé du même montant. 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.



Quand une nouvelle tentative est rejetée

La plupart des nouvelles tentatives sont échangées 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'échange. La plupart des intégrations n'en ont pas besoin.



Prochaines étapes