Skip to main content

Rate and concurrent request limits

Zuora

Rate and concurrent request limits

This article describes the request rate limits and concurrent request limits that Zuora enforces to maximize the stability of its service.

Rate limits

Zuora employs a number of tenant-level rate limits against bursts of incoming traffic to maximize the stability of its service. Note that the rate limits are in addition to, and independent of, the concurrent request limits.

Rate-limiting and quotas

Zuora sets limits on the type and number of requests that a tenant can make per minute, per hour, and per day. All incoming requests are classified as follows:

Zuora enforces the following rate limits on each tenant.

Request type Quota per minute Quota per hour Quota per day 
UI 20,000 1,200,000 14,400,000
Authentication 2,000 67,500 810,000
API 50,000 2,250,000 27,000,000

We recommend that you treat these limits as maximums and avoid generating unnecessary load. We may reduce limits to prevent abuse, or increase limits to enable high-traffic applications. To request an increased rate limit, contact Zuora Global Support.

RateLimit response headers

Zuora counts your UI, authentication and API requests in the time window of one minute, one hour or one day.  The system communicates the quota that you are closest to exhausting in the HTTP response header in compliance with the IETF draft policy for rate limiting v2.

HTTP response header Description
RateLimit-Limit The request limit quota for the time window closest to exhaustion.
RateLimit-Remaining The number of requests remaining in the time window closest to quota exhaustion.
RateLimit-Reset The number of seconds until the quota resets for the time window closest to quota exhaustion.

Use cases

Consider that you have a tenant with the default rate limits of API requests. Assume that your tenant's API request numbers for the current time windows at a certain point of time are as follows:

Time window API request rate limit API request number for the current time window
One minute 50,000 49,500
One hour 2,250,000 2,249,600
One day 27,000,000 25,900,000

At this time point, you are closest to exhausting the hourly limit of API requests. If you make an API request, the response headers convey the hourly rate limit information of your tenant. You can see the rate limit information as in the following snippet of the response headers:

HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Limit : 2250000, 50000;w=60, 2250000;w=3600, 27000000;w=86400
RateLimit-Remaining : 399
RateLimit-Reset : 1200

Error messages

In the above use case, the headers inform that you can make, at most, 399 API requests further in the next 1,200 seconds (or 20 minutes). Suppose that you make 399 API requests within the next 10 minutes, and then if you make the 400th API request at the time point of 10 minutes before the current time window is closed, you will receive a response with HTTP status code 429 - Too Many Requests and a response body in JSON as follows:

HTTP/1.1 429 - Too Many Requests
Content-Type: application/json
RateLimit-Limit : 2250000, 50000;w=60, 2250000;w=3600, 27000000;w=86400
RateLimit-Remaining : 0
RateLimit-Reset : 600

{
  "reasons": [
    {
      "code": 70,
      "message": "API Rate limit exceeded for the <minute|hour|day>, retry after 600 seconds"
    }
  ]
}

Concurrent request limits

Zuora employs a number of tenant-level concurrent request limits to maximize the stability of its service.

If the Multi-entity feature is enabled in your tenant, the concurrent request limits are enforced on the entity-level. Each entity is subject to the concurrent request limits individually.

Concurrent request limit types

Zuora applies different request limits to different types of requests. The request limits are:

  • Total Request limit - 40 concurrent requests by default
    Most UI and API requests are counted towards your Total Request limit.
    Some requests require a large amount of processing or data transfer. The following additional concurrent limits apply to such requests:

    • Big Process Request limit - 20 concurrent requests by default. All big process requests are also counted towards your Total Request limit. The requests that require heavy database operations are big process requests. For example, requests for retrieving payments for a specified account. See the Big Process Requests table below for more information.

    • Big Data Request limit - 20 concurrent requests by default. All big data requests are also counted towards your Total Request limit.

  • Custom Request limit - 200 concurrent requests by default. Custom requests are NOT counted towards your Total Request limit.

See the following table for the concurrent request limits that apply to different product areas.

Product Area Operations Total Request Limit Big Data Request Limit Big Process Request Limit Custom Request Limit

Subscriptions

Subscribe and amend REST method calls:

Subscribe and amend SOAP calls, and the corresponding Action calls in the Zuora API Reference:

      checkmarkGreen_xsm.png
Orders

Orders:

  • Preview order
  • Create order
      checkmarkGreen_xsm.png

Orders:

  • All requests except Preview order and Create order
checkmarkGreen_xsm.png      
Login Login Requests:
  • Login API calls (REST and SOAP) 
  • UI login requests

(No applicable concurrent limit for Login requests)

       
HPM

Hosted Payment Method Pages:

      checkmarkGreen_xsm.png
CPQ Zuora 360 Order Builder (includes APEX wrappers for SOAP APIs) checkmarkGreen_xsm.png      
Zuora for Salesforce
  • 360 Sync
  • Zuora Quotes

(No applicable concurrent limit)

       
AQuA AQuA API requests
  • Post query
  • Get job results
  • Get results files
checkmarkGreen_xsm.png      
AQuA results files download checkmarkGreen_xsm.png checkmarkGreen_xsm.png    
Usage

Usage request

  • Post usage
checkmarkGreen_xsm.png checkmarkGreen_xsm.png    

Usage request

  • Check import status
checkmarkGreen_xsm.png      
Data Source Export Data source file download checkmarkGreen_xsm.png checkmarkGreen_xsm.png    
Invoicing

Transactions

  • Get payments
checkmarkGreen_xsm.png   checkmarkGreen_xsm.png  

Big process requests

SOAP API calls on some objects are handled as Big Process Requests. See the following table for details. The corresponding REST API Actions are also handled as big process requests.

SOAP API Calls Objects
Create invoice
Generate invoice
QueryMore

Account

InvoiceItem

PaymentTransactionLog

RatePlan

RatePlanCharge

RatePlanChargeTier

Subscription

Query

Account

Invoice

InvoicePayment

Payment

PaymentTransactionLog

RatePlan

RatePlanCharge

Subscription

Usage

Errors when reaching concurrent request limits

You will encounter the following error codes, error messages, or HTTP status codes:

Request Type Error Code Error Message HTTP Status Code - Response Header
User Interface N/A "The total number of concurrent requests has exceeded the limit allowed by the system. Please resubmit your request later."

N/A

REST API 50000070 "The total number of concurrent requests has exceeded the limit allowed by the system. Please resubmit your request later."

HTTP Status:429

Response Header:  “Retry-After:120"

SOAP API, version 51.0 and later

<fns:FaultCode>
REQUEST_EXCEEDED_LIMIT
</fns:FaultCode>

<fns:FaultMessage>
The total number of concurrent requests has exceeded the limit allowed by the system. Please resubmit your request later.
</fns:FaultMessage>

HTTP Status:429

Response Header:  “Retry-After:120"

SOAP API, versions prior to 51.0

<fns:FaultCode>
UNKNOWN_ERROR </fns:FaultCode>

<fns:FaultMessage>
The total number of concurrent requests has exceeded the limit allowed by the system. Please resubmit your request later.
</fns:FaultMessage>

HTTP Status:429

Response Header:  “Retry-After:120"

File Download API N/A "The total number of concurrent requests has exceeded the limit allowed by the system. Please resubmit your request later."

HTTP Status:429

Response Header:  “Retry-After:120"

Zuora recommends that you retry sending the request after 120 seconds.

We recommend that you test your integration in Zuora Sandbox and make sure you do not hit the concurrent request limits. Contact Zuora Global Support if you require additional assistance. 

Other Limitations

Limitation on Memo PDF

Up to 20,000 line items are allowed in a single memo PDF.

Limitation on Invoice PDF 

Zuora limits the sum total of certain line items up to a maximum number in a single invoice. For example, the sum total of line items for invoice items, taxation items, and usage items in a single invoice cannot exceed 20,000. 

Maximum sum total of 20,000 is allowed for the following line items:

  • invoice item
  • taxation item
  • usage item

Maximum sum total of 2,000 is allowed for the following line items:

  • credit balance adjustment
  • invoice adjustment
  • invoice item adjustment
  • payment
  • refund

Maximum sum total of 2,000 is allowed for the following line items:

  • subscription
  • rate plan

When generating an invoice PDF, if the maximum number is exceeded, an error message is generated.

Amendments per Subscription

Zuora recommends that you create no more than 100 amendments on a subscription to ensure high performance of the subscriptions. The limit of amendments allowed on a subscription is 1000. However, if you create more than 100 amendments, the performance may be severely degraded, depending on the products and charges set up in your subscription.

If the renewal term period of the latest version of the subscription is Day or Week, the limit of amendments allowed on a subscription is 100.

The 100 amendment limit does not apply to Orders. See Orders Performance Guidance for more information.

Limitations on Orders

Orders is now generally available as of Zuora Billing Release 284 (August 2020).

If you are an existing Zuora Subscribe and Amend customer and want to adopt Orders, see What is Orders Harmonization and join the Orders Harmonization community group for more information. If you want to enable Orders, submit a request at Zuora Global Support.

The limit of orders allowed on a subscription is 1000.

Zuora has the following limits on the Orders synchronous API to prevent performance degradation:

If you have an Order that exceeds any limits of the above, Zuora recommends you use the following asynchronous API operations:

Zuora has the following limits on the Orders asynchronous API operations to prevent performance degradation:

If you have a need for a large order that exceeds any limits of the above, you can request a limit increase for the Orders asynchronous API by submitting a request at Zuora Global Support.