xproxy_result Limit states

The Payi service will return a xproxy_result object which will contain a state object for each limit evaluated in the processing of the request. These states can be used by your code to choose the appropriate actions to manage spend from , such as by switching to a cheaper end-to-end solution, stopping further requests, or up-selling your user.

State	Description
`ok`	`spend < max * threshold` The amount spent is still below the limit's Risk Threshold
`exceeded`	`spend >= max * threshold AND spend <= max` The amount spent has reached or exceeded the limit's Risk Threshold but is less than or equal to the limit's `max`. NOTE: this state is not blocked - requests are still allowed.
`overrun`	The amount of spend has exceeded the limit's `max`. Mathematically: spend > max. For an `Allow` limit, all further requests will result in the `overrun` limit state. For a `Block` limit, only the request which causes the spend to exceed the limit's `max` will have the `overrun` limit state. All further requests will result in the `blocked` limit state.
`blocked`	`spend > max AND limit_type == block` This limit has blocked the request. This only occurs when a `block` limit's spend has already gone over its `max` ( `spend > max` ) and an additional request is attempted.
`blocked_external`	`blocked_external`*can only appear when multiple limits are used for a single request, and at least one of them is of type`block`. The following example illustrates when`blocked_external` is used. Limit A, type: `allow` Limit B, type: `block` A request is made declaring both limits, A and B. Limit A allows the request. Limit B blocks the request. The state of the request for Limit B is `blocked`. The state of the request for Limit A is `blocked_external`, indicating the request was blocked by another limit that was part of the same request. All reported limit states are stored and can be reviewed with the Get Limit Details API. Refer to Understanding Limit Details.

IMPORTANT: A common misconception is that when a limit state is "exceeded" the requests are blocked. This is not correct. The "exceeded" state simply means spending has reached or passed the threshold but is still below or equal to the max value. Requests are still allowed in the "exceeded" state. Only the "blocked" state (for Block limits) actually prevents requests. The mathematical definitions for each state are provided below.

Limit State Diagram

For Block limits, the request which causes the budget to exceed its maximum will have the overrun state. All further requests will have the blocked state.

Limit State Examples

Allow

max = $10.00
threshold = 0.8
Risk Threshold = $8.00

#	Spend (Before)	Request Cost	Spend (After)	State	Overrun	Explanation
1.	$7.80	$0.19	$7.99	`ok`	$0.00	$7.99 < $8.00 `(threshold)`
2.	$7.99	$2.00	$9.99	`exceeded`	$0.00	$9.99 > $8.00 `(threshold)` AND $9.99 ≤ $10.00 `(max)`
3.	$9.99	$0.30	$10.29	`overrun`	$0.29	$10.29 > $10.00 `(max)`
4.	$10.29	$0.50	$10.79	`overrun`	$0.79	$10.79 > $10.00 `(max)`

Block

max = $10.00
threshold = 0.8
Risk Threshold = $8.00

#	Spend (Before)	Request Cost	Spend (After)	State	Overrun	Explanation
1.	$7.80	$0.19	$7.99	`ok`	$0.00	$7.99 < $8.00 `(threshold)` "ok"
2.	$7.99	$2.00	$9.99	`exceeded`	$0.00	$9.99 > $8.00 `(threshold)` AND $9.99 ≤ $10.00 `(max)`
3.	$9.99	$0.30	$10.29	`overrun`	$0.29	$10.29 > $10.00 `(max)`
4.	$10.29	N/A	$10.29	`blocked`	$0.29	`spend (before)` > `max`