Tiempos de espera de las solicitudes de la API de Claude y «se recomienda encarecidamente el streaming»: la regla de los 10 minutos

Normalmente hay tres tiempos de espera entre tú y el modelo: el del SDK, el de un intermediario y la propia regla del proveedor sobre las llamadas largas sin streaming; gana el más corto. Aumentar solo el del SDK explica por qué esto sigue ocurriendo después de creer que lo habías solucionado.

El error

two shapes

# Rejected before generating, for a long non-streaming request:
{"type":"error","error":{"type":"invalid_request_error",
 "message":"Streaming is strongly recommended for operations that may take
 longer than 10 minutes."}}

# Or the client-side companion, with no response at all:
APITimeoutError: Request timed out.

Causas y soluciones de un vistazo

Causa	Solución
Una generación larga sin streaming	Transmítela. Las finalizaciones largas están diseñadas para transmitirse, no para esperar a que terminen.
El tiempo de espera del cliente del SDK es menor que la generación	Auméntalo, pero aumenta también el límite del intermediario o nada cambiará.
Un proxy, equilibrador de carga o función sin servidor que limita la solicitud	Encuentra el límite más corto de la cadena; ese es el que estás alcanzando.
Conexión aceptada, pero nunca respondió	No es una respuesta lenta, sino un bloqueo. Limita por separado el tiempo hasta el primer byte.

Transmite todo lo que pueda durar más de un par de minutos

Además de evitar el límite, el streaming proporciona una señal de actividad: si llegan tokens, significa que el modelo está trabajando, por lo que un bloqueo puede distinguirse de un progreso lento. Con una única llamada bloqueante, ambos casos parecen idénticos hasta que se activa el tiempo de espera.

Aumenta todos los tiempos de espera de la cadena, no solo el del SDK

Casi siempre se cambia el cliente y se da el trabajo por terminado. Si un proxy inverso o una plataforma sin servidor limita la solicitud por debajo del nuevo tiempo de espera del cliente, el límite sigue prevaleciendo y el síntoma no cambia.

client.py

from anthropic import Anthropic

# Client timeout is only one of the limits in play.
client = Anthropic(api_key=KEY, timeout=600.0)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=8192,
    messages=[{"role": "user", "content": prompt}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Limita por separado el tiempo hasta el primer byte y la duración total

Son dos fallos distintos que necesitan dos soluciones diferentes. Un plazo breve para el primer byte detecta rápidamente una conexión inactiva; un plazo total amplio permite que termine una generación realmente larga. Un único tiempo de espera combinado no puede hacer ambas cosas.

Haz que los reintentos sean seguros antes de añadirlos

Una solicitud cuyo tiempo de espera se agotó por tu parte puede haber terminado correctamente en el servidor. Si el trabajo tiene efectos secundarios o se te cobra por llamada, añade idempotencia en tu capa antes de incorporar un bucle de reintentos.

Si llamas a través de Kunavo

Kunavo publica sus propias cifras en lugar de obligarte a descubrirlas: espera como máximo 240 segundos a las cabeceras de respuesta del servidor ascendente, y una respuesta sin streaming normalmente envía sus cabeceras solo cuando está completa, por lo que una llamada sin streaming que necesite más tiempo no terminará a través de la puerta de enlace; transmítela. El límite de 240 segundos se aplica únicamente al tiempo hasta las cabeceras y se libera en cuanto llegan, así que nunca trunca un stream largo; nada más en la puerta de enlace limita la duración de un stream. Lo que sí lo termina es el silencio: 300 segundos sin un byte del servidor ascendente o 600 segundos sin un byte en la conexión contigo. Las rutas síncronas de imagen, vídeo y música mantienen la conexión durante un máximo de 540 segundos mientras termina el renderizado, dentro de esa ventana de 600 segundos, porque los renderizados legítimamente tardan minutos. Una solicitud cuyo tiempo de espera se agota antes de las cabeceras cuenta como un fallo del canal, se reintenta en el siguiente canal del modelo cuando hay uno configurado y se registra con coste cero.

Preguntas frecuentes

¿Se cobra una solicitud cuyo tiempo de espera se agotó?

En Kunavo, no: las solicitudes fallidas se registran con coste cero. La facturación directa con un proveedor depende de si la generación llegó a producirse.

¿Por qué el streaming evita el límite?

La respuesta comienza en segundos y la conexión permanece activa, por lo que ningún periodo individual de silencio es lo bastante largo como para activar un tiempo de espera.

¿Cuál debería ser el tiempo de espera de mi cliente?

Más largo que tu generación realista más lenta, acompañado de un plazo breve independiente para el primer byte. Un único tiempo de espera combinado y largo convierte cualquier bloqueo en una espera de varios minutos.

Guías relacionadas

Encontrarás más detalles sobre el significado de los errores en referencia de errores; obtener una clave lleva un minuto mediante registro y la guía de autenticación.