Idempotencia, límites y reintentos

Idempotency-KeyCopiar enlace

Las escrituras que cambian contactos o conversaciones, o que envían mensajes, exigen la cabecera Idempotency-Key. Con ella, repetir una solicitud no repite su efecto: un mensaje no sale dos veces y un contacto no se crea dos veces.

Crear o desactivar un webhook y reintentar una entrega no usan esta cabecera.

ReglasCopiar enlace

• Genera un valor único por cada escritura lógica, por ejemplo un UUID v4. Debe tener entre 8 y 200 caracteres.
• La clave de idempotencia vale para tu clave de API. Otra clave de API puede usar el mismo valor sin conflicto.
• Ricky compara el método, la ruta y el cuerpo. Repite los tres exactamente iguales al reintentar.
• Sin la cabecera, o con un valor fuera de rango, la respuesta es 400 missing_idempotency_key.
• Ricky valida la solicitud antes de leer la cabecera. Un cuerpo inválido o una conversación que no existe reciben su error aunque la cabecera falte.

curl https://getricky.ai/api/v1/contacts \
  -H "Authorization: Bearer $RICKY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" \
  -d '{"first_name": "Ana", "last_name": "Pérez", "primary_phone": "+507 6000-1234"}'

Qué responde Ricky al repetir una claveCopiar enlace

La misma clave con otro método, otra ruta u otro cuerpo recibe 409 idempotency_conflict.

Estado desconocidoCopiar enlace

Después de un 5xx, Ricky no sabe si el efecto ocurrió, así que la misma clave sigue respondiendo 409 request_processing. Haz esto:

1. Lee el recurso para saber si la escritura ocurrió. Por ejemplo, después de enviar un mensaje, lista los mensajes de la conversación.
2. Si ocurrió, no hagas nada más.
3. Si no ocurrió, repite la escritura con una Idempotency-Key nueva.

Una clave nueva siempre crea un efecto nuevo. Úsala solo cuando sepas que el primer intento no ocurrió. Si no puedes saberlo, escribe a soporte con el X-Request-Id.

Límite de solicitudesCopiar enlace

Cada clave de API admite 120 solicitudes por minuto. La ventana es el minuto del reloj: se reinicia en el segundo 0 de cada minuto.

Toda respuesta a una clave válida, exitosa o con error, incluye:

Al superar el límite, la respuesta es 429 rate_limited con Retry-After, en segundos, y las mismas cabeceras X-RateLimit-*. Espera ese tiempo antes de enviar otra solicitud con esa clave.

Si tienes que procesar muchos registros, reparte las solicitudes en el tiempo y lee X-RateLimit-Remaining antes de cada lote.

ReintentosCopiar enlace

Reintenta solo lo que puede tener éxito sin cambios. Espera más entre cada intento: retroceso exponencial con una variación aleatoria, por ejemplo 1, 2, 4, 8 y 16 segundos, hasta un máximo de 5 intentos. Si la respuesta trae Retry-After, espera al menos ese tiempo.