Service Limits¶

Service limits control the amount of data consumed through a specific service. They can apply one allowance to the whole service or use a campaign's classes to give identified users different allowances. The rule can enforce daily and monthly windows, send early-warning emails, and block, redirect, or continue traffic at exhaustion.

Because service limits affect live requests, treat the service, identification method, unit, values, and limit-reached action as production-critical configuration.

Choose how to limit the service¶

The Limit By field has two values:

Limit By	Counter scope	Additional configuration	Typical use
`service`	The service as a whole.	Daily/monthly values on the service limit.	A shared allowance for all traffic through one service.
`service_and_user`	An identified user within the service.	Campaign, active campaign classes, and user identifier header.	Per-user allowances such as sponsored-data tiers.

If the requirement is an overall allowance across several services belonging to one entity, use an Entity Limit instead.

How a campaign-based limit works¶

When service_and_user is selected:

Select a campaign that contains active campaign classes.
The portal loads the class names, identifiers, units, and daily/monthly values into the service-limit configuration.
The gateway reads the user ID from the configured request header. The default header name is X-Obsidian-User-Id.
The surrounding integration associates the request with the intended campaign/class configuration.
Usage is counted for that user and evaluated against the applicable daily and monthly allowances.

Campaign-class selection and fallback behaviour are solution-specific. Confirm the exact header/class mapping with the service owner, especially before relying on a default class.

Service Limits list¶

Open Gateway > Service Limits. The list shows the enabled state, linked service, daily and monthly limits, unit, limit dimension, creation date, and actions. Search by the visible service or limit details and use filters to narrow the result.

If a limit is missing, first confirm that your role can access the service and its entity. A service limit may also be created from a service workflow, in which case the service is already supplied by that workflow.

Before you create a service limit¶

Confirm:

the exact service;
whether the allowance is shared or per user;
for per-user limits, the campaign and its active classes;
the request header that contains a stable user ID;
the unit and daily/monthly allowance;
the exhaustion action;
threshold percentages and recipients; and
approved Redis, fault-tolerance, and Lambda settings.

Use a test environment to inspect real requests. Do not assume a header is present because it appears in an architecture document.

Create a service limit¶

Open Gateway > Service Limits and select Create Service Limit.
Keep Enabled off until testing and approval are complete.
Select the Service.
Select Limit By.
For service_and_user, select a campaign with active classes and confirm the User Identifier Header.
Select the Unit of Measure.
Select the Limit Reached Action and, for redirect, add an approved location.
Decide the Fault Tolerant behaviour.
Enter at least one of Daily Limit or Monthly Limit.
Configure daily/monthly threshold notifications as required.
Change Redis or Lambda fields only when the platform design requires it.
Save, test, and then enable the rule through the approved change process.

Service limit and threshold workflow

The workflow screenshot shows the same service-limit concepts inside guided service setup. The standalone page may arrange the fields differently.

Core field guide¶

Field	Required	What it controls	Guidance
Enabled	Yes	Whether the gateway includes this rule in limit checks.	Save disabled while preparing or reviewing a rule.
Service	Yes	The one service protected by the rule.	Confirm the name and owning entity. It is fixed when the limit is created within a service workflow.
Limit By	Yes	Whether counters are shared by service or separated by service and user.	Choose `service` or `service_and_user`; changing this later changes the meaning of the counters.
Campaign	For `service_and_user`	The campaign supplying active classes and their allowances.	The selected campaign must contain usable active classes.
User Identifier Header	For `service_and_user`	The request header name that contains the user ID.	Defaults to `X-Obsidian-User-Id`. Use letters, numbers, and dashes, and match the caller exactly.
Unit of Measure	Yes	The scale of daily and monthly values.	Choose `gigabytes`, `megabytes`, `kilobytes`, or `bytes`; the form defaults to megabytes.
Limit Reached Action	Yes	The response when an allowance is exhausted.	Choose hard block, hard redirect, or soft alert.
Redirect Location	For redirect	Destination returned with redirected traffic.	Add at least one valid, approved hostname or IP address.
Fault Tolerant	Yes	Whether service access continues if the live counter cannot be calculated.	Decide with the service and platform owners.
Daily Limit	Conditional	Maximum consumption in the daily window.	Must be zero or greater. At least Daily or Monthly is required.
Monthly Limit	Conditional	Maximum consumption in the monthly window.	Must be zero or greater. Daily cannot be greater than Monthly when both are set.

Limit-reached actions¶

Hard-limit (block traffic)¶

The gateway rejects traffic with HTTP 429 Too Many Requests. Use this for a strict cap. Clients should stop or back off rather than retrying continuously, which would add load without restoring allowance.

Hard-limit (redirect traffic)¶

The gateway returns HTTP 301 Moved Permanently with the configured location, intended to redirect traffic to standard-rated billing. Test the exact client: browsers and API clients do not all follow redirects in the same way.

Soft-limit (alerts received)¶

The gateway sends alerts but allows traffic to continue. Choose this for monitoring or manual intervention, not for a strict data/spend cap.

Threshold notifications¶

Daily and monthly thresholds are configured independently. Each can have:

an Action (currently email);
a Type (currently alert);
a Percentage Value from 0 to 100; and
one or more valid Notification Recipients.

An 80% daily threshold on 500 MB alerts at 400 MB. A separate 80% monthly threshold is calculated against the monthly allowance. Reaching a threshold does not reset usage or replace the action taken at 100%.

Send notifications to a monitored team address and test delivery before enabling a hard limit. An unread warning defeats the purpose of early notification.

Campaign and class change impact¶

Selecting a campaign loads its campaign classes into the service limit. The saved service-limit configuration contains a copy of their identifiers and allowance values. If a class is added, removed, activated, or changed later, review the service limit again and confirm that the intended classes and values are present.

Avoid changing a live class identifier without coordinating the caller. A mismatch may send users to the wrong allowance or prevent the intended class from being resolved. For substantial changes, a new class identifier and controlled migration are easier to test and roll back.

Counter policy and Redis¶

The Policy can be redis or local; Redis is the portal default. Redis allows gateway nodes to use a shared counter store. A local policy keeps data at an individual node and may not represent one total in a multi-node deployment.

Redis fields include host, port, password, timeout, database, SSL, SSL verification, and SNI server name. The form initially shows values such as localhost, port 6379, timeout 2000 ms, and database 0. Treat them as form defaults, not guaranteed environment settings.

Do not change these fields without platform approval. Incorrect connectivity can prevent the gateway from calculating limits and makes Fault Tolerant behaviour immediately important.

Fault tolerance¶

Fault Tolerant answers: “If the gateway cannot calculate the real-time allowance, should the service remain accessible?”

Availability-oriented behaviour allows traffic while the counter system is unavailable, but usage may exceed the intended cap.
Enforcement-oriented behaviour blocks access when the counter cannot be trusted, but a counter-store outage can interrupt legitimate users.

Document the chosen behaviour and test it in a controlled failure scenario. The correct choice depends on whether continuity or strict sponsored-usage enforcement has priority.

Optional Lambda events¶

The rule can invoke AWS Lambda when a limit is reached and when it is released. It can reuse one function or call separate functions and qualifiers. Supporting fields include AWS authentication, assumed role, region, host/port, invocation and log types, timeout, keep-alive, proxy/HTTPS settings, and IMDS protocol version.

These options are for an approved integration—for example, billing or operational automation—not required for an ordinary limit. Prefer inherited IAM-role authentication where the platform design supports it, and never expose AWS credentials in screenshots or support messages.

Safe rollout and test cases¶

Create the rule disabled and verify at least these cases in a non-production environment:

A normal request below the threshold succeeds.
The daily threshold produces the expected email.
The monthly threshold produces the expected email.
A request at exhaustion produces the selected 429, 301, or soft-limit behaviour.
For per-user limits, two different user IDs maintain separate usage.
A missing, empty, or malformed user ID is handled as the solution expects.
Each campaign class receives its own intended allowance.
The counter-store failure produces the approved availability/enforcement result.
Any reached/released Lambda functions receive and process their events.

After testing, restore production values, obtain approval, enable the rule, and monitor alerts and gateway responses.

Edit or retire a service limit¶

Open the service limit, make the change, and save. Re-test when changing Limit By, campaign, header name, unit, daily/monthly values, action, counter policy, or fault tolerance. These changes alter either who shares a counter or what happens to live requests.

To retire a limit, disable it first and monitor the service. Delete only after confirming that no workflow or campaign depends on it and the rollback period has passed.

Troubleshooting¶

A user reaches the limit too early¶

Check both the daily and monthly counters.
Confirm the unit and campaign-class values.
Verify that each user sends a unique, stable identifier.
Check whether multiple devices or applications share one user ID.
Review recent class and service-limit changes.

Confirm Limit By is service_and_user, the expected header name is configured, and each request contains a distinct value. If Limit By is service, shared counting is expected.

The campaign cannot be selected or does not load¶

Confirm the campaign exists and contains at least one active class with usable values. Save the classes and reload the service-limit page. Check your access to the campaign's entity.

Requests are blocked when Redis is unavailable¶

Review the Redis connection and the configured fault-tolerant behaviour. Check host, port, password, database, SSL/SNI, and timeout errors. Do not switch to local policy as an emergency workaround unless the service owner understands the counter-consistency impact.

Redirect does not work¶

Confirm the selected action is hard redirect, the location is valid and approved, and the client follows HTTP 301 responses. Inspect the response's Location value during a controlled test.