Badge Lookup: Optional Rate-Limit Settings

The badge lookup endpoint (GET api/v2/lookup) protects the system from overload and abuse with built-in limits. No configuration is required. Each client account may make up to 100 lookups per second, with short bursts of up to 200. At most 64 lookups are processed at once across all clients. An IP address that sends more than 20 failed (unauthenticated or unauthorized) requests per second is temporarily refused. An account whose traffic is mostly "not found" results (300 or more per minute) is treated as possible enumeration and runs at half its limit for 5 minutes. When a limit is reached, the caller receives 429 TooManyRequests (per-client limits) or 503 ServiceBusy (system-wide limit), both with a Retry-After header giving the number of seconds to wait before retrying.

These defaults suit most sites. If your traffic pattern requires different limits, you can override any of them by adding keys to the <appSettings> section of the IdExchange WebApi Web.config file. Add only the keys you want to change; any key you leave out keeps its default.

Key	Default	Purpose
`LookupClientRatePerSecond`	`100`	Sustained lookups per second allowed for one client
`LookupClientBurst`	`200`	Lookups one client may send in a short burst
`LookupClientKeyMode`	`account`	How a client is identified: `account`, `ip`, or `header` (account plus the `X-Station-Id` header, for per-station limits)
`LookupMaxInFlight`	`64`	Lookups processed at the same time across all clients
`LookupPreAuthFailuresPerSecond`	`20`	Failed requests per second allowed from one IP address before it is refused
`LookupEnumerationNotFoundPerMinute`	`300`	"Not found" results per minute that flag a client for possible enumeration

XML

<appSettings>
  <!-- existing keys -->
  <add key="LookupClientRatePerSecond" value="150" />
  <add key="LookupClientBurst" value="300" />
</appSettings>

Saving Web.config restarts the application pool automatically, and the new values take effect on the next lookup. To confirm the change, check the WebApi log for a warning that begins lookup guard limits overridden in Web.config; it lists the values in use. A value that is not a positive number is ignored, and the default is used and logged instead. To return to the defaults, remove the keys and save the file. Set limits high enough for your busiest period. Values that are too low cause legitimate scans to be refused with 429 or 503.