Rate Limiting (TokenBucket)
To ensure fair usage and protect the stability of key and QR Code consultation services, FitBank applies a rate-limiting mechanism based on a TokenBucket model. This control follows the same logic adopted by the Brazilian Central Bank (BC) for DICT consultations, replicated by FitBank for consistency.
Affected methods
Token consumption applies exclusively to the following consultation methods:
| Method | Description |
|---|---|
GetInfosPixKey | Consult Pix Key information (DICT) |
GetInfosPixHashCode | Consult Pix QR Code information by decoding its Hash |
No other PIX API method is subject to this control.
Initial bucket size
| Account type | Initial tokens |
|---|---|
| Individual (PF) | 50 |
| Company (PJ) | 100 |
Consumption rules
| Scenario | Tokens consumed |
|---|---|
| Successful consultation | 1 |
| Invalid hash | 1 |
| QR Code no longer available for payment (paid / canceled / expired) | 1 |
| Communication failure or temporary unavailability | 1 |
| Pix key or QR Code not found in DICT | 20 (1 + 19 penalty) |
The 19-token penalty is applied only when the consultation confirms that the Pix key or QR Code genuinely does not exist in DICT — following the rule established in the DICT Manual. No other error scenario is penalized.
Token refill
Refill on successful payment
If a token was consumed during a consultation and the corresponding payment is later completed successfully, the token is returned to the client's bucket.
Automatic refill
Tokens are continuously replenished at an approximate rate of 1 to 2 tokens per minute, independent of usage.
Updated about 1 hour ago