Polling and limits

Use webhooks for charge and withdrawal status updates. Repeated reads of one entity are limited to 30 requests per 60 seconds per account and entity, across API keys. Different entities have independent budgets. Charge aliases share the same budget, including public IDs with the ch_ prefix and raw IDs.

This applies to GET /v1/charges/:id, GET /v1/payments/:id and GET /v1/withdrawals/:id (and any registered GET /v1/pix/charges/:id alias). Collection reads and creation are unchanged.

On HTTP 429, check error.code = entity_rate_limited and wait at least the number of seconds in Retry-After. Use exponential backoff with jitter; do not rotate API keys to retry. The counter uses a fixed 60-second window starting with the first read. Operators can configure the budget with ENTITY_READ_LIMIT_PER_MINUTE; 0 disables it. If Redis is unavailable, reads continue.

An account receives at most one polling email per UTC day, in its communication language, recommending webhooks. Operations receives an account-specific alert after more than 100 throttles in a ten-minute window, at most once per UTC day. Delivery is best effort.