VALIDATA Developers

API

Idempotencia

Toda validación exige Idempotency-Key: entre 16 y 128 caracteres, empieza por letra o número y admite A-Z a-z 0-9 . _ ~ : -. Usa una clave por pedido.

Reglas#

  • Mismo ámbito: comercio + integración. La misma clave en otra integración es otra operación.
  • Mismo Idempotency-Key y el mismo cuerpo (incluido event_at) → réplica de la respuesta original, sin nuevo cobro (REPLAY_NOT_CHARGED).
  • Misma clave con otro cuerpo → 409 IDEMPOTENCY_CONFLICT. Usa otra clave solo si es realmente otro pedido.
  • Misma clave mientras la primera sigue en curso → 409 OPERATION_PENDING. Consulta el readback; no cambies de clave.

Cuándo reintentar#

RespuestaQué hacer
503 SERVICE_UNAVAILABLEReintenta con la misma clave y el mismo cuerpo, con espera creciente y un tope de intentos. Puede que el servicio sí haya procesado la solicitud: el reintento recupera ese resultado sin cobrar dos veces.
429 RATE_LIMITEDEspera los segundos de Retry-After y reintenta.
409 OPERATION_PENDINGConsulta el readback hasta que haya resultado.
Cualquier DO_NOT_RETRYNo reintentes; corrige la causa.

Las respuestas selladas se conservan 7 días (valor configurado, sujeto a confirmación): pasado ese plazo, la misma clave vuelve a ejecutarse. Usa siempre una clave nueva por pedido.

Genera event_at una vez por pedido y reutilízalo en los reintentos.