Error 429 — Collections

El error 429 en la API de Cobros indica un intento de alterar el estado de un cobro que ya se encuentra en un estado final o que está temporalmente bloqueado para modificaciones.

Resumen del problema

Una llamada de PUT o DELETE que retorna 429 indica que la operación no puede ejecutarse sobre el cobro en el estado actual. El cobro llegó al servidor correctamente, pero la transición de estado solicitada es inválida.

Motivos recurrentes

Cobro ya cancelado

Un cobro con status CANCELED está en estado final y no puede ser alterado ni cancelado nuevamente. Cualquier PUT o DELETE sobre él retornará 429.

Consulta el status actual del cobro vía GET /{companyId}/banking/collections/{collectionId} antes de ejecutar operaciones de escritura.

Cobro ya pagado

Un cobro con status PAID está en estado final. Los intentos de actualización (PUT) o cancelación (DELETE) retornarán 429.

Cobro pagado a la espera de liquidación (ventanas CIP)

Este es el caso más sutil: el cobro está técnicamente con status PAID, pero aún no ha sido liquidado (settledAt ausente). En ese estado, permanece bloqueado para modificaciones hasta que la liquidación sea procesada.

La liquidación de boletos ocurre en dos ventanas diarias definidas por la CIP:

Ventana	Horario de corte	Liquidación
Ventana 1	Hasta las 13:30	14:00 del mismo día
Ventana 2	Después de las 13:30	2:00 del día siguiente

Los boletos pagados después de las 13:30 caen en la ventana de las 2:00 y solo se liquidan en la madrugada siguiente. Durante ese intervalo, los intentos de PUT o DELETE retornarán 429.

Resolución: espera la liquidación del cobro e intenta la operación nuevamente después de la ventana correspondiente.

Diagnóstico rápido

1. Consulta el status actual del cobro vía GET /{companyId}/banking/collections/{collectionId}
2. Si el status es CANCELED o PAID con settledAt rellenado, el cobro está en estado final y no puede ser alterado
3. Si el status es PAID sin settledAt, el cobro está a la espera de liquidación — verifica el horario del pago y espera la ventana CIP correspondiente (14:00 o 2:00)
4. Si el status es PROCESSING o UPDATING, espera la conclusión del procesamiento antes de intentar nuevamente

Si el problema persiste después de estos pasos, ponte en contacto con el equipo de soporte a través del correo ImplantacaoEmpresas@btgpactual.com.