Client Ban
Client Ban Policy is a policy that temporarily blocks clients exceeding a predefined number of errors or error rate within a specific time window.
This policy utilizes the circuit breaker pattern to automatically block clients that continuously send failing requests, helping to protect system resources.
How It Works
When a client sends a request, the policy first identifies the client by combining the values of specified variables to generate a unique client key.
The system creates a CircuitBreakerForClientBan for this client and checks its current state.
If the circuit breaker is open (i.e., the client is currently blocked):
If "Enable Retry-After Header" is enabled, a Retry-After header is added to the response.
The request is rejected, and an error is returned to the client.
If the circuit breaker is closed (i.e., the client is not blocked), the request proceeds as normal.
After the request is processed but before the response is sent:
The policy's error handling method is invoked.
A Response Assertion condition is checked.
If the condition fails (indicating an error), the error counter is incremented.
If the number or rate of errors exceeds the configured threshold, the circuit breaker is triggered (opened), and the client is blocked for the duration of the Ban Time.
This policy is designed to protect APIs from clients sending repeated failed requests or malicious attacks.
For example, it helps to block clients that continuously send invalid credentials, repeat requests that result in errors, or stress the system, thereby protecting system performance and security.
A visual representation of the policy settings is provided below:
The fields used for policy configuration are shown in the table below:
Field | Description |
|---|---|
Name | A name can be written to make the policy easier to use and manage. You will need this name when managing and selecting policies. |
Description | A description can be written to facilitate the use and management of the policy. |
Variable List for Client Identity | A list of variables used to identify the client. These variables (e.g., IP address, user ID, API key) are used to uniquely identify the client. The values of these variables are combined to create a unique key for the client. |
Threshold Window in seconds | Defines the time window in seconds for calculating the error threshold. For example, if set to 10 seconds, the system will monitor errors within the last 10 seconds. |
Threshold Count per Window | Defines the maximum allowed number of errors within the specified time window. If this number is exceeded, the client is blocked for the defined duration. |
Ban Time in seconds | Defines the duration (in seconds) for which the client will be blocked. After this time expires, the client is allowed to make requests again. |
Threshold Calculation Type | Determines how the error threshold is calculated. COUNT: Blocking occurs after a specific number of errors. PERCENT: Blocking occurs when a certain percentage of the total requests are errors. |
Enable Retry-After Header | Determines whether the "Retry-After" HTTP header will be added to responses during blocking. When set to TRUE, blocked clients will receive a header specifying when they can try again. |
If the client's identity cannot be determined, this policy should be applied or the request should be rejected with an error message. When active, this control is ignored if the client's identity cannot be determined. | |
Response Assertion | Defines the condition used to decide whether the client will be blocked. This condition checks the response, and if the condition is not met (i.e., an error occurs), the error count is incremented. |
You can visit the Policies page for the details of the Conditions and Error Message Customization panels.