How is provisioned throughput capacity calculated?

IBM Cloudant calculates provisioned throughput capacity by totaling the usage for each request class per second, where 1 second is a sliding window. When an account exceeds the total number of a request class that is allotted by its plan, IBM Cloudant rejects subsequent requests of that request class. No new requests are accepted until the usage of that request class inside the sliding window falls under the allowed limit. The sliding 1-second window is any consecutive period of 1,000 milliseconds.

For example, the Standard plan instance limits you to 200 reads per second. When you exceed 200 read requests, IBM Cloudant rejects future read requests made during the sliding 1,000-millisecond window. Read requests resume when the number of read requests for that time period is less than 200.

Request class units do not necessarily have a one-to-one mapping with HTTP requests. A single HTTP request can consume multiple units of a request class or classes if, for example, it reads multiple documents or both reads and writes.

What happens when I exceed the provisioned throughput capacity limit?

When you exceed the number of allowed events, IBM Cloudant generates a 429 Too Many Requests response. You must make sure ahead of time that your applications can handle 429 responses.

If you use the most recent versions of the client libraries that IBM Cloudant supports, you can set up your applications to handle 429 responses. This step is important because most client libraries don't automatically attempt to retry a request when a 429 response occurs. You need to verify that your application handles 429 responses correctly because IBM Cloudant limits the number of retries. Regularly exceeding the number of requests indicates that you need to move to a different plan.