Rate Limits

What is Rate Limiting?

Rate limiting is a technique used to control the number of API requests a client can make within a specified time window. This helps ensure fair usage, protects the API from abuse or accidental overload, and maintains overall system stability and performance. When a client exceeds the allowed limit, the API typically responds with a 429 Too Many Requests status, often accompanied by information on when they can retry.

What Endpoints Are Affected?

Currently, only the order placement endpoint of PropertyInsight has a rate limit.

How Does it Work?

When making a request to the above endpoint, you'll see these response headers:

• X-Rate-Limit-Limit: The total number of requests allowed for this endpoint during the rate limit period
• X-Rate-Limit-Remaining: The remaining number of requests allowed for the rate limit during this period
• X-Rate-Limit-Reset: The Unix timestamp (seconds since epoch) when the rate limit will reset

The Betterview API has a rate limit period of one minute. This means you can expect the limit to reset within 60 seconds.

What Happens if I Exceed the Rate Limit?

Exceeding the rate limit has different effects depending on the options being used on the order placement endpoint.

• Sync (isSyncResponse=true): The request will be rejected. It can be retried after X-Rate-Limit-Reset has occurred.
• Async (isSyncResponse=false): A bit of nuance here. There is only an effect when sending "async" requests with a single address. The rate limit, in this case, refers to getting fast processing treatment on that order. Exceeding the rate limit will cause subsequent orders to be accepted, but they will be processed by our bulk system. The request could still process very quickly, but we're leaving room for the bulk system to scale when handling large volumes. If the "async" request includes more than one address (a bulk request), there is no rate limit. Those addresses will all be sent to the bulk processing system and handled in appropriate order. An "async" request is never rejected from rate limits.

How Do I Use It?

Typically, the rate limit becomes important if you're implementing a process that requires high concurrency. An example would be supporting a user interface that allows them to process an address, and your system supports many concurrent users. A period of high activity might cause your requests to exceed the rate limit. The rate limit information could be used in a couple different ways depending on how your system batches and sends requests.

A system that funnels all the requests through a single processor could watch X-Rate-Limit-Remaining until a request causes the value to be 0, then pause processing until X-Rate-Limit-Reset is the current timestamp before continuing. This would cause you to never receive a 429 Too Many Requests rejection from rate limits.

A distributed system might have many processing instances all sending requests to Betterview concurrently. X-Rate-Limit-Remaining may not help here, as any processing instance could use the last remaining request within the period, and none of the other processing instances would know to wait. In this case, each processing instance could be coded to react to 429 Too Many Requests rejection and wait for X-Rate-Limit-Reset before continuing.