Reintentos

Qué errores se reintentan, con qué espera y cómo lo hacen los SDK de Trevol; cuándo reintentar con cURL.

Cada error de la API trae retryable: si es true, repetir la petición puede funcionar; si es false, corrige primero. Los SDK reintentan solos lo reintentable y nunca reintentan lo que podría duplicar un efecto.

Qué se reintenta

Con los SDK (hasta 2 reintentos por defecto, maxRetries):

un error de red o un tiempo agotado, sin respuesta;
los estados 429, 500, 502, 503 y 504;
un 409 con code request_in_progress o previous_event_pending;
cualquier problema con retryable: true, salvo 402.

Solo cuando la operación es segura de repetir: los GET, los preview, los PATCH y todo POST/PUT con Idempotency-Key (la misma clave en cada intento). Los POST sin clave —crear o rotar un endpoint de webhook, test, resend, send— y los DELETE solo se reintentan con 429.

Qué no se reintenta

Nunca se reintentan las respuestas 2xx (incluidos todos los 202), ni 400, 401, 402, 403, 404, 422, ni los 409 finales: invalid_state, external_id_in_use, duplicate_document, file_unavailable y webhook_limit_reached.

Cuánto se espera

Espera creciente con azar: min(0,5 · 2^(intento−1), 8) segundos por un factor entre 0,75 y 1. Si la respuesta trae Retry-After, se espera lo que sea mayor entre ese valor y la espera calculada. Si Retry-After pide más que maxRetryAfter (60 s), el SDK no espera: lanza el error con retryAfter para que decidas tú.

Con cURL

Reintenta tú, con espera creciente, los 429, 5xx y los errores con retryable: true, y manda la misma Idempotency-Key en cada intento. Respeta Retry-After. No reintentes un 202: espera el webhook o consulta el documento.