Consultas periódicas y límites

Usa webhooks para recibir actualizaciones del estado de cobros y retiros. Las lecturas repetidas de una misma entidad están limitadas a 30 solicitudes cada 60 segundos por cuenta y entidad, sumando todas las claves de API. Cada entidad tiene su propio límite independiente. Los alias de un cobro comparten el mismo límite, incluidos los ID públicos con el prefijo ch_ y los ID sin procesar.

Esto se aplica a GET /v1/charges/:id, GET /v1/payments/:id y GET /v1/withdrawals/:id (y a cualquier alias GET /v1/pix/charges/:id registrado). Las lecturas de colecciones y las operaciones de creación no cambian.

Si recibes un HTTP 429, revisa error.code = entity_rate_limited y espera al menos el número de segundos indicado en Retry-After. Usa un retroceso exponencial con variación aleatoria (jitter); no rotes las claves de API para reintentar. El contador usa una ventana fija de 60 segundos que comienza con la primera lectura. Los operadores pueden configurar el límite con ENTITY_READ_LIMIT_PER_MINUTE; el valor 0 lo desactiva. Si Redis no está disponible, las lecturas continúan.

Una cuenta recibe como máximo un correo electrónico sobre consultas periódicas por día UTC, en su idioma de comunicación, con la recomendación de usar webhooks. El equipo de operaciones recibe una alerta específica de la cuenta cuando se superan los 100 bloqueos por límite en una ventana de diez minutos, como máximo una vez por día UTC. La entrega se realiza en la medida de lo posible.