Protecciones en el retiro Pix por clave

Visión General

Antes de enviar un retiro por clave, el proveedor de liquidación consulta la clave en el directorio de Pix (DICT). Ese proveedor limita las consultas y puede bloquear temporalmente la cuenta que repite consultas de claves inexistentes. Cuando eso ocurre, todos los retiros de la cuenta se ven afectados.

Para evitarlo, la plataforma responde al instante con lo que ya sabe y evita consultas repetidas que harían que el proveedor bloquee la cuenta. Hay tres comportamientos, que usted percibe en la respuesta de POST /api/pix/cash-out:

Repetir una clave ya negada no bloquea la cuenta ni al cliente: solo esa clave tiene su respuesta guardada (15 minutos, o hasta 30 si el proveedor la niega otra vez en hasta 2 horas) y la plataforma devuelve la misma negativa sin consultar al proveedor. Todas las demás claves siguen normales.

Clave inexistente (422)

Cuándo ocurre: el primer intento con una clave inexistente sigue el flujo normal de su cuenta: con aceptación asíncrona, la API responde 201 y después recibe el webhook de fallo indicando que la clave no fue encontrada; con aceptación síncrona, el error vuelve en la propia respuesta. Si el proveedor respondió hace poco que la clave no existe, la negativa puede llegar ya en el primer intento de su cuenta. Cuando el proveedor responde que la clave no existe, la plataforma guarda esa respuesta durante 15 minutos. Durante ese tiempo, los nuevos envíos a esa clave reciben la misma negativa directamente de la plataforma (422 PIX_KEY_NOT_FOUND, details.cached: true), sin consultar al proveedor.

• Si, después de vencer, el proveedor niega la misma clave otra vez dentro de 2 horas, el nuevo registro vale 30 minutos. Ese es el máximo; nunca lo supera.
• Los intentos respondidos por la plataforma no cuentan y no prorrogan el plazo. Solo cuenta una nueva negativa del propio proveedor.
• Solo esa clave se ve afectada. La cuenta, el cliente y todas las demás claves siguen normales. No es un bloqueo ni una sanción.
• Por qué existe: el proveedor aplica una regla del DICT que suspende durante cerca de 30 minutos todos los retiros por clave de la cuenta cuando se consulta repetidamente la misma clave inexistente. Guardar la respuesta protege toda la cuenta.
• Una clave recién registrada puede tardar hasta ese plazo en ser aceptada.
• Sin transacción, sin reserva de saldo y sin webhook.
• El externalId de la solicitud rechazada no queda consumido y puede reutilizarse.

{
  "code": "PIX_KEY_NOT_FOUND",
  "message": "Chave Pix não encontrada",
  "details": {
    "retryAfterSeconds": 780,
    "source": "provider-guard",
    "cached": true
  }
}

retryAfterSeconds (y el encabezado Retry-After) traen siempre el tiempo real que falta.

Qué hacer: trátelo como el fallo de clave no encontrada que llegaría por webhook: pida al usuario que revise la clave. Si la clave se registró hace poco, espere retryAfterSeconds e intente de nuevo.

La negativa de clave inexistente puede llegar de dos formas. Trate ambas como la misma situación (la clave no existe): corríjala antes de reenviar.

Línea de tiempo de ejemplo:

10:00  Retiro a la clave X
       -> 201, luego webhook de fallo "clave no encontrada"
10:02  Nuevo retiro a la clave X
       -> 422 inmediato desde el registro, retryAfterSeconds ~ 780, cached: true
10:15  El registro vence
10:16  Nuevo retiro a la clave X
       -> consulta de nuevo al proveedor
       -> si niega otra vez, nuevo registro de 30 minutos (hasta las 10:46)

Retiro ya aceptado: en cuentas con aceptación asíncrona (respuesta 201 y resultado por webhook), la clave puede registrarse como inexistente después de que el retiro fue aceptado y antes de enviarse al proveedor, por ejemplo cuando se envían varios retiros a la misma clave al mismo tiempo. En ese caso el retiro se cierra con error de clave inexistente y el valor reservado se libera, exactamente como si el proveedor lo hubiera negado. El aviso llega por el webhook de fallo normal. En cuentas con aceptación síncrona la misma verificación ocurre en la propia llamada y el error vuelve en la respuesta.

Proveedor bloqueando consultas (429)

Cuándo ocurre: el proveedor bloqueó temporalmente las consultas de clave. Mientras siga bloqueando, la mayoría de los retiros por clave con documento del receptor informado se rechaza al instante, sin transacción, sin reserva y sin webhook.

• Dura solo mientras el proveedor esté bloqueando.
• Cada 30 segundos, como máximo un retiro se libera para probar si el proveedor volvió. Ese retiro se acepta normalmente (201) y, si el bloqueo continúa, termina en error por el webhook, con el valor reservado devuelto. Cuando la prueba funciona, la protección termina.
• Ese bloqueo es del proveedor (regla de consultas al DICT), no una sanción de la plataforma. La protección existe precisamente para evitar que ocurra.

La respuesta trae el encabezado Retry-After y details.retryAfterSeconds (60).

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "code": "TOO_MANY_PIX_KEYS_NOT_FOUND",
  "message": "Muitas tentativas com chaves Pix inexistentes. Saque por chave bloqueado temporariamente; tente novamente em instantes.",
  "details": {
    "retryAfterSeconds": 60,
    "source": "provider-guard"
  }
}

Qué hacer: espere el tiempo de Retry-After e intente de nuevo, con backoff si el rechazo persiste. No se creó ni reservó nada.

10:00  El proveedor bloquea las consultas de clave
10:00  Retiro por clave con documento -> 429 inmediato, Retry-After: 60
10:00:30  Un retiro se libera como prueba -> 201, si el proveedor sigue bloqueando, webhook de fallo
10:01  Nuevo intento -> 429 (sigue bloqueado)
10:03  El proveedor libera; la plataforma lo detecta sola
10:03  Nuevo intento -> 201, flujo normal

Límite de ritmo del proveedor (envío más lento)

Cuándo ocurre: el volumen de consultas se acerca al límite del proveedor.

Qué responde la API: el retiro se acepta normalmente (201) y puede tardar hasta 90 segundos más en enviarse al proveedor. El resultado llega por webhook como siempre. La espera solo se aplica a retiros con documento del receptor informado, en cuentas con aceptación asíncrona; los retiros sin documento no se retrasan.

Qué hacer: nada. No reenvíe el retiro por la demora: consulte primero su estado (vea Monitoreo de Estado).

10:00:00  Retiro aceptado -> 201 (PENDING)
10:01:20  Retiro enviado al proveedor (retraso de hasta 90 s)
10:01:23  Webhook con el resultado

Qué cambia para quien integra

Mejores prácticas

• Trate PIX_KEY_NOT_FOUND con cached: true exactamente como el fallo de clave no encontrada que llegaría por webhook: pida al usuario que revise la clave.
• Al recibir PIX_KEY_NOT_FOUND, corrija la clave antes de reenviar. No haga reintento automático de la misma clave y respete retryAfterSeconds.
• No repita en bucle la misma clave inválida: la respuesta será la misma hasta que venza el plazo.
• Respete Retry-After y details.retryAfterSeconds, con backoff si el rechazo persiste.
• Informe details.document del receptor siempre que lo conozca: los errores llegan al instante y no minutos después por webhook.
• No reenvíe el mismo retiro sin comprobar su estado. La idempotencia es por externalId; vea PIX Cash-Out.

Preguntas frecuentes