Crédito de respaldo
Evita pagar dos veces el costo de la caché de prompts cuando reintentas en otro modelo una solicitud rechazada.
Las cachés de prompts son por modelo. Cuando un modelo rechaza una solicitud y reintentas en otro modelo, el prefijo de la conversación ya almacenado en caché para el primer modelo debe escribirse desde cero en la caché del nuevo modelo. Las escrituras en caché cuestan más que las lecturas de caché. El "fallback credit" (crédito de respaldo) elimina ese costo adicional. El rechazo incluye un token de crédito, tú devuelves el token en el reintento, y el reintento se factura como si la conversación hubiera estado en el nuevo modelo desde el principio.
Necesitas esta página solo cuando construyes el reintento tú mismo: sobre HTTP sin procesar o con lógica de reintento personalizada. El respaldo del lado del servidor y el middleware del SDK aplican el crédito de respaldo automáticamente. Si usas cualquiera de los dos, omite esta página.
Rechazos y respaldo cubre cómo detectar rechazos y elegir un enfoque de respaldo. Almacenamiento en caché de prompts explica las lecturas de caché y las escrituras en caché si esos términos son nuevos para ti.
El flujo básico
Actívalo con el encabezado beta
Envía la solicitud que podría ser rechazada con el encabezado
anthropic-beta: fallback-credit-2026-07-01. El encabezadoserver-side-fallback-2026-07-01también otorga los mismos campos, y el encabezado anteriorfallback-credit-2026-06-01sigue siendo aceptado y otorga los mismos campos.Lee dos campos del rechazo
En un rechazo,
stop_detailsincluye dos campos:fallback_credit_token: una cadena opaca que representa el crédito.fallback_has_prefill_claim: un booleano que te indica qué forma de cuerpo de reintento usar.
Ambos son
nullcuando no hay crédito disponible para el rechazo.Construye el reintento
Parte del cuerpo de la solicitud rechazada. Establece
modelen el modelo de respaldo y agrega el token como el parámetro de nivel superiorfallback_credit_token. Elige la forma del cuerpo según la siguiente tabla.Envía el reintento con el mismo encabezado
Envía el reintento con el mismo encabezado beta
fallback-credit-2026-07-01. El reintento necesita el encabezado para canjear el token.
El campo fallback_has_prefill_claim te indica si el reintento puede continuar la salida parcial del modelo que rechazó en lugar de empezar de nuevo:
fallback_has_prefill_claim | Cuerpo del reintento |
|---|---|
true | El cuerpo de la solicitud rechazada, sin cambios, más un mensaje de asistente añadido al final cuyo content replica el content de la respuesta rechazada. El modelo de reintento continúa la respuesta desde donde se detuvo el modelo que rechazó, y las llamadas a herramientas de servidor completadas no se vuelven a ejecutar. |
false | El cuerpo de la solicitud rechazada, sin cambios. |
Ejemplo
El siguiente ejemplo realiza una solicitud que podría ser rechazada y canjea el token de crédito en un reintento contra Claude Opus 4.8. Cuando un intento de reintento es rechazado, el ejemplo desciende por la escalera de rechazos: la secuencia de formas de reintento progresivamente más simples que se cubre en Cuando un reintento es rechazado.
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}
# Prefiere la forma de continuación a menos que la afirmación sea 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:
# Recurre al cuerpo sin cambios, aún con el token
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
# El token en sí fue rechazado: descártalo y reintenta sin él.
response = send("claude-opus-4-8", request)
print(json.dumps({"stop_reason": response.stop_reason, "model": response.model}))Dónde funciona
El crédito de respaldo está en beta en la Claude API, Amazon Bedrock, Claude Platform en AWS, Google Cloud y Microsoft Foundry. Los rechazos en Message Batches no emiten tokens de crédito, y el canje se aplica solo a solicitudes directas de la Messages API: un token pasado en una solicitud por lotes se acepta pero se ignora.
El modelo de reintento debe ser uno de los destinos de respaldo permitidos del modelo que rechazó. Para Claude Fable 5.1 y Claude Fable 5, estos son Claude Opus 4.8 (claude-opus-4-8) y Claude Opus 5 (claude-opus-5).
En la Claude API y Claude Platform en AWS, la lista de destinos se publica como allowed_fallback_models en la entrada de cada modelo en la Models API cuando se establece el encabezado beta server-side-fallback-2026-07-01. La lista aún no es visible solo con el encabezado fallback-credit-*. No se expone en Amazon Bedrock, Google Cloud ni Microsoft Foundry.
Verificar que el crédito se aplicó
El reembolso es visible en el usage del reintento. En comparación con lo que la misma solicitud reportaría sin el token, cache_creation_input_tokens es menor y cache_read_input_tokens es mayor en la misma cantidad. Un cambio de cero significa que el token fue aceptado pero no había nada que recalcular, por ejemplo porque la caché del modelo de reintento ya estaba caliente.
Cuando un reintento es rechazado
La mayoría de los reintentos se canjean en el primer intento. Cuando uno no lo hace, la API devuelve un error 400 que te indica qué probar a continuación.
Continuación rechazada: reenvía el cuerpo sin cambios
Si el reintento que añade el mensaje de asistente es rechazado con un error 400, reenvía el cuerpo de la solicitud rechazada sin cambios, aún con el token.
Token rechazado: descarta el token
Si el cuerpo sin cambios también es rechazado con un error 400 cuyo mensaje menciona
fallback_credit_token, reintenta sin el token. El crédito se pierde, pero el reintento en sí se procesa.
Este rechazo es transitorio, no un veredicto sobre la forma de tu reintento. Reintenta la misma solicitud, con el mismo token, dentro de la ventana de cinco minutos del token. No pases al siguiente paso de la escalera.
Referencia
Las siguientes secciones cubren casos límite y las reglas completas de canje. La mayoría de las integraciones no las necesitan.
El canje compara el reintento con la solicitud rechazada. Cada campo que da forma al prompt debe coincidir exactamente. Los campos que no dan forma al prompt pueden cambiar en el reintento.
| Regla | Campos |
|---|---|
| Deben coincidir exactamente | system, messages, tools, tool_choice, thinking y cache_control, además de output_config, mcp_servers, context_management y container cuando los usas |
| Pueden cambiar en el reintento | model, max_tokens, stop_sequences, temperature, top_p, top_k, stream, metadata y service_tier |
La forma de continuación (fallback_has_prefill_claim: true) es la única excepción a la coincidencia de messages: agrega exactamente un mensaje de asistente al final de messages.
No elimines los bloques thinking o redacted_thinking de turnos anteriores en el reintento, aunque un reintento simple sin token normalmente los elimina. El cuerpo debe coincidir con la solicitud rechazada, y el servidor maneja esos bloques por sí mismo.
Envía los mismos encabezados anthropic-beta en el reintento que en la solicitud rechazada. Un encabezado beta presente en una de las dos solicitudes pero no en la otra puede hacer fallar la coincidencia incluso cuando los cuerpos son idénticos. El error 400 resultante lleva el mismo mensaje request body ... does not match que una diferencia en el cuerpo, por lo que es fácil confundir una diferencia de encabezados con un problema del cuerpo. En particular, no agregues ni elimines encabezados beta según el modelo al que se dirige la solicitud.
Dos familias de encabezados están exentas de la coincidencia, en beneficio del reintento:
server-side-fallback-*: un reintento debe eliminar el parámetrofallbacks, y eliminar este encabezado junto con él no causa una discrepancia.fallback-credit-*: mantén este encabezado en ambas solicitudes. El reintento lo necesita para canjear el token.
El campo es null solo cuando el token también es null, por lo que un valor que observes mientras tienes un token nunca es null. Aun así puede estar ausente (None en los SDK tipados) en Amazon Bedrock, Google Cloud y Microsoft Foundry mientras se despliega su soporte para el campo. En ese caso, trata la forma del reintento como desconocida en lugar de como false. Prueba primero la forma con el mensaje de asistente añadido, y apóyate en el manejo de rechazos de Cuando un reintento es rechazado, que recurre al cuerpo sin cambios.
Cuando el token de un rechazo admite la forma de continuación, el content de la respuesta contiene solo la salida propia del modelo, y la explicación del rechazo se entrega en stop_details.explanation. Por lo tanto, puedes replicar content en el mensaje de asistente añadido tal como está.
Aun así, pueden ser necesarios dos ajustes antes de enviar:
- Si el bloque final que envías es un bloque
text, elimina sus espacios en blanco finales. - Omite cualquier bloque
tool_usedel lado del cliente que no tenga untool_resultcorrespondiente.
Si el contenido replicado incluye un bloque fallback de un respaldo del lado del servidor anterior, mantén el bloque exactamente donde apareció. Se acepta en cualquier solicitud sin un encabezado beta. La API usa su posición para validar los bloques de pensamiento a su alrededor, por lo que una solicitud que replica bloques de pensamiento de ambos lados de ese límite es rechazada si el bloque se omite o se mueve.
El token se canjea solo desde la organización y el espacio de trabajo que recibieron el rechazo, incluso en Microsoft Foundry. En Amazon Bedrock y Google Cloud, que no tienen espacios de trabajo, el token está vinculado en su lugar a la identidad del llamador de la plataforma.
El token expira cinco minutos después del rechazo. Después de eso, envía el reintento sin él. El token también es sin estado: el servidor no almacena nada sobre él, y no hay ningún endpoint para inspeccionarlo o revocarlo.
Cuando el rechazo llegó después de que las herramientas de servidor ya se habían ejecutado dentro de la solicitud, el token se canjea solo continuando la respuesta parcial. Esa restricción es lo que evita que las llamadas a herramientas completadas se ejecuten, y se facturen, de nuevo.
Por lo tanto, una combinación puede dejar el token sin posibilidad de canje con ninguna de las dos formas, cuando se cumplen ambas condiciones siguientes:
- La solicitud usó
output_config.formato untool_choiceque fuerza el uso de herramientas. Cualquiera de los dos descarta la forma con el mensaje de asistente añadido. - El rechazo llegó después de que se ejecutaran herramientas de servidor. Eso descarta el cuerpo sin cambios.
Si el reintento con el cuerpo sin cambios es rechazado con un error 400 que dice que el token debe canjearse continuando la respuesta parcial, descarta el token. Un reintento sin él se procesa, pero vuelve a ejecutar y vuelve a facturar las herramientas de servidor completadas. Muestra el costo o el error a quien te llamó en lugar de reintentar silenciosamente.
Próximos pasos
Detecta rechazos y elige entre el respaldo del lado del servidor, el middleware del SDK y un reintento manual.
Cómo se facturan las lecturas de caché y las escrituras en caché.
Cada valor de stop_reason y cómo manejarlo.
El asistente del SDK que aplica el crédito de respaldo automáticamente.
Was this page helpful?