Entity Limits

Entity limits place a shared data-usage allowance over an entity's services. Use them for an overall customer, tenant, or business-unit allowance rather than an allowance for one service or one identified user.

An entity limit is implemented by the portal's global-limit gateway configuration. It can enforce a daily limit, a monthly limit, or both; warn recipients before the allowance is exhausted; and block, redirect, or continue traffic when the limit is reached.

Entity limit or service limit?

Requirement	Use
Control total usage across an entity's services	Entity Limit
Control usage for one service	Service Limit with Limit By = service
Give different users campaign-class allowances on one service	Service Limit with Limit By = service_and_user

Entity and service limits can exist at the same time. Review all limits in the request path when diagnosing unexpected blocking; passing one limit does not guarantee that another applicable limit has not been reached.

Entity Limits list

Open Gateway > Entity Limits. The list shows the entity, enabled state, daily limit and threshold, monthly limit and threshold, creation date, and available actions. Search and filters help narrow the records; list and grid buttons change only the presentation.

Before editing, confirm the entity name and both time windows. A value that looks correct in the table can still be wrong if its unit or limit-reached action is not what the business expects.

Before you create an entity limit

Obtain approval for:

• the entity to protect;
• the unit of measure;
• the daily and monthly allowances;
• the action at exhaustion;
• the warning percentages and recipients;
• whether usage should continue if the counter store is unavailable; and
• any non-default Redis or Lambda configuration.

Also check for an existing entity limit. Multiple active global limits for the same entity can be difficult to reason about and may produce an unexpected effective allowance.

Create an entity limit

1. Open Gateway > Entity Limits.
2. Select New Entity Limit.
3. Leave Enabled off while preparing or reviewing the rule.
4. Select the Entity.
5. Choose the Unit of Measure and Limit Reached Action.
6. If redirecting, add at least one approved Redirect Location.
7. Decide the Fault Tolerant behaviour.
8. Enter a daily limit, a monthly limit, or both.
9. Add threshold settings and notification recipients if required.
10. Leave Redis and Lambda settings at their approved environment defaults unless the platform team supplied alternatives.
11. Save the limit, test it, then enable it through the normal change process.

Core field guide

Field	Required	What it controls	Guidance
Enabled	Yes	Whether the gateway includes this limit in its checks.	Keep off until the values and runtime settings have been reviewed.
Entity	Yes	The entity whose services share the allowance.	This is the most important scope field. Confirm it before saving.
Unit of Measure	Yes	The scale used by daily and monthly values.	Available values are gigabytes, megabytes, kilobytes, and bytes; the default shown by the form is megabytes.
Limit Reached Action	Yes	The response after the allowance is exhausted.	Choose hard block, hard redirect, or soft alert according to the approved business rule.
Redirect Location	For redirect	The allowed destination used for redirected traffic.	At least one valid hostname or IP address is required when redirect is selected.
Fault Tolerant	Yes	Whether access continues when the real-time limit cannot be calculated.	This is a business continuity versus strict-enforcement decision.
Daily Limit	Conditional	The maximum usage in the daily period.	Must be zero or greater. At least one of Daily or Monthly is required.
Monthly Limit	Conditional	The maximum usage in the monthly period.	Must be zero or greater. If both are supplied, Daily cannot be greater than Monthly.

Limit-reached actions

Hard-limit (block traffic)

When the allowance is exhausted, the gateway rejects traffic with HTTP 429 Too Many Requests. Use this for strict caps where continued consumption is not permitted. Calling applications should be able to handle a 429 response without continuously retrying.

Hard-limit (redirect traffic)

The gateway returns HTTP 301 Moved Permanently and a location that redirects traffic to the configured standard-rated billing destination. Use only an approved location and test client behaviour; not every API client follows redirects in the same way.

Soft-limit (alerts received)

Alerts are sent, but traffic continues. Use this when the allowance is for monitoring, notification, or operational intervention rather than immediate blocking.

Warning

Soft-limit does not stop further usage. If the business requirement is a strict spending or traffic cap, select and test a hard-limit action.

Daily and monthly thresholds

Thresholds provide an early warning before the corresponding allowance is exhausted. The portal currently supports an alert threshold type with an email action.

For each period, configure:

• Action — currently email;
• Type — currently alert;
• Percentage Value — from 0 to 100; and
• Notification Recipients — one or more valid email addresses.

For example, an 80% threshold on a 500 GB monthly allowance alerts at 400 GB. The threshold does not replace the limit-reached action; it provides advance notice while the configured hard or soft action still applies at the full allowance.

Use monitored team mailboxes where possible. Review recipients whenever responsibility for the entity changes.

Counter storage and resilience

The Policy determines where limit counters are maintained:

• redis uses the configured Redis server and is the portal default;
• local keeps counters locally on a gateway node.

Redis is normally appropriate when several gateway nodes must share one consistent allowance. Local counters may differ between nodes and should be used only when the solution design explicitly allows that behaviour.

Redis settings include host, port, password, timeout, database, SSL, certificate verification, and SNI server name. Defaults in the form include localhost, port 6379, timeout 2000 ms, and database 0; these are form defaults, not proof that they are correct for an environment.

Fault Tolerant controls what happens when the gateway cannot calculate the live value. Enabling it favours availability; disabling it favours strict enforcement. Test the agreed failure scenario before production use.

Lambda notifications

Optional Lambda settings can invoke a function when a limit is reached and another when it is released. The same function may be used for both events, or separate function names and qualifiers can be supplied.

These settings include AWS credentials or inherited IAM-role authentication, region, host, invocation type, log type, timeout, and keep-alive values. They are platform settings, not ordinary business fields. Ask the platform team for approved values, and never copy secrets into tickets, screenshots, or documentation.

Safe rollout and verification

1. Save the limit disabled.
2. Confirm the entity and unit in the list.
3. Test with a deliberately small allowance in a non-production environment.
4. Verify the threshold email at the configured percentage.
5. Verify the response at the full allowance: 429, 301, or continued traffic.
6. Verify the daily/monthly reset behaviour expected by the solution.
7. Test the approved counter-store failure behaviour.
8. Restore the approved values and enable the limit.
9. Monitor alerts and gateway errors after release.

Edit or retire an entity limit

Open the record, make the change, and save it. A unit or allowance change can immediately affect every service in the entity, so apply the same review as a new limit. If the entity is being migrated, disable the old limit only after the replacement has been tested.

Prefer disabling an obsolete limit before deletion. This provides a rollback window and preserves configuration for troubleshooting.

Troubleshooting

An entity is blocked unexpectedly

• Check both daily and monthly consumption.
• Confirm the unit shown on the rule.
• Check whether more than one enabled entity limit exists.
• Review service limits that may also apply.
• Check recent changes and whether several services share the same entity allowance.

Threshold emails are not received

• Confirm the relevant daily or monthly limit exists.
• Check that the percentage is between 0 and 100.
• Validate every recipient address and the monitored mailbox's spam/quarantine rules.
• Confirm the platform threshold action and outbound email service are operational.

The limit behaves differently on different requests

Check the counter policy and gateway topology. If local policy is used across several nodes, counters may not represent one shared total. For Redis, check connectivity, database selection, SSL/SNI settings, timeout errors, and the configured fault-tolerant behaviour.