ReportingCloud

Quotas and Limits

Topic

A ReportingCloud plan sets how many documents and spell checking requests an account can run per month and how many templates it can store. On top of that, the Web API limits how many merge requests an account runs at once and how long a document request may take. A request that crosses one of these limits returns 403 Forbidden, the same status that refused credentials get, or its task is canceled after 60 seconds. Find out first which limit you reached, then look up the problem below.

The quota of each plan is listed on Plans and Licensing.

Find Out Which Limit You Reached

  1. Make sure the credentials are accepted: GET /v1/account/settings returns 200 with the same Authorization header, as Test the Credentials on Their Own shows. If it returns 403 too, or the 403 body reads Invalid username/password combination or invalid APIKey, the problem is the credentials, not a limit.
  2. Compare each count of the response with its maximum: createdDocuments with maxDocuments, uploadedTemplates with maxTemplates and proofingTransactions with maxProofingTransactions. A count that has reached its maximum names the quota that is used up.
  3. In the portal, Statistics shows the quota usage of the current month and of earlier months, and the Transaction Monitor lists each transaction of the current month with the API key that sent it. Transactions and Statistics describes the two pages.

Which endpoint counts against which quota is listed in What Counts Against Which Quota, and the 403 causes of each endpoint in Forbidden.

Document Requests Return 403 Forbidden

Merge, append, convert, find and replace, thumbnail or removetrackedchange requests return 403 Forbidden. GET /v1/account/settings returns 200, and createdDocuments has reached maxDocuments.

The document quota of the month is used up. Each successful request of an endpoint that counts against it adds 1 to createdDocuments, and once the count reaches the maximum of the plan, these endpoints refuse further requests.

  1. Compare createdDocuments with maxDocuments, or open Statistics in the portal.
  2. While you develop and test, add the parameter test=true to merge, append, convert and find and replace requests, so that they don't count against the quota. On a trial account, only the test runs of append and convert are not counted; those of merge and find and replace are. Test Mode describes the parameter, which isn't available on Free accounts.
  3. If the account needs more documents, move to a plan with a higher quota, as Upgrading to a Subscription describes.

Don't open further Free accounts to get around the quota: the services agreement doesn't allow it, as Trial and Free Account explains.

If createdDocuments is still below maxDocuments and only merge requests are refused, read the next section.

Merge Requests Return 403 While Quota Is Left

Some merge requests return 403 Forbidden and others succeed, while createdDocuments is below maxDocuments. The requests run in parallel: an application sends one request per record in a parallel loop, for example, or several applications use the same account.

POST /v1/document/merge returns 403 when more than two requests of the same account run at the same time. The limit applies to the account, so requests with different API keys of one account count together.

  1. Send at most two merge requests of the account at the same time, for example by processing the records through a queue with two workers.
  2. Send a refused request again after one of the running requests has returned.
  3. Merge several records with one request instead of sending one request per record. The mergeData array takes several records, and the service creates one document per record, or a single document when append is true. Keep each request within the 60-second limit described below.

With the .NET SDK, Parallel.ForEach limits the number of requests that run at once. The following console application merges four invoices from the demo template sample_invoice.tx, never more than two at a time:

using TXTextControl.ReportingCloud;

ReportingCloud rc = new ReportingCloud(
    Environment.GetEnvironmentVariable("REPORTINGCLOUD_API_KEY"));

string[] invoiceNumbers = { "778723", "778724", "778725", "778726" };

// Run at most two merge requests of the account at the same time
ParallelOptions options = new ParallelOptions { MaxDegreeOfParallelism = 2 };

Parallel.ForEach(invoiceNumbers, options, invoiceNumber =>
{
    MergeBody body = new MergeBody
    {
        MergeData = new[] { new { invoice_no = invoiceNumber } }
    };

    List<byte[]> documents = rc.MergeDocument(body, "sample_invoice.tx", ReturnFormat.PDF);

    File.WriteAllBytes($"invoice-{invoiceNumber}.pdf", documents[0]);
});

The code works as follows:

  • MaxDegreeOfParallelism = 2 lets Parallel.ForEach run the loop body for two records at a time, so the application never has more than two merge requests open.
  • MergeDocument sends one request to document/merge and returns the created documents as byte arrays. The SDK throws an ArgumentException with the response body as its message when the service refuses a request.
  • Each record fills only the field invoice_no here. A real application passes the complete invoice data, as Merge Data describes.

A Request Returns an HTML 403 Page

A request returns 403 Forbidden with an HTML page, HTTP Error 403.501 - Forbidden, instead of a plain-text message, and the same request succeeds a few seconds later. The SDKs pass the page on as the message of their exception.

The web server limits, on every endpoint, how many requests from one IP address run at the same time, and refuses a request over the limit with this page.

  1. Wait a few seconds and send the request again.
  2. Send fewer requests from that address at the same time, for example through a queue, as Merge Requests Return 403 While Quota Is Left shows for merge requests.

Forbidden describes the page.

The Template Storage Is Full

POST /v1/templates/upload returns 403 Forbidden, while GET /v1/account/settings returns 200.

The template storage quota of the plan is used up: uploadedTemplates, the number of templates in the storage, has reached maxTemplates. An upload under a new name adds 1 to the count, an upload that replaces a stored template of the same name doesn't, and deleting a template lowers it again.

  1. Compare uploadedTemplates with maxTemplates, or count the templates with GET /v1/templates/count.
  2. List the templates with GET /v1/templates/list and delete those you no longer need, with DELETE /v1/templates/delete or under My Templates in the portal.
  3. For a template you use rarely, send it with the merge request instead of storing it, in the template field of the MergeBody. Send the Template With the Request compares the two ways.
  4. If the account needs more templates in the storage, move to a plan with more storage, as Upgrading to a Subscription describes.

If uploadedTemplates is still below maxTemplates, look at the name: the upload answers the same 403, with the message Template quota exceeded, for a templateName of more than 207 characters or one that contains # or /. Upload the template under a shorter name without these characters.

Spell Checking Requests Return 403

GET /v1/proofing/check or GET /v1/proofing/suggestions returns 403 Forbidden, while GET /v1/account/settings returns 200.

The spell checking quota of the month is used up: proofingTransactions has reached maxProofingTransactions. Each request of the two endpoints adds 1 to the count.

  1. Compare proofingTransactions with maxProofingTransactions in the response of GET /v1/account/settings.
  2. If the account needs more spell checking requests, move to a plan with a higher spell checking quota, as Upgrading to a Subscription describes.

Spell Checking describes the two endpoints and their quota.

A Request Is Canceled After 60 Seconds

A merge with many records, or a conversion or thumbnail request for a large document, runs for a minute and doesn't return the document.

The processing time of a document request is limited to 60 seconds, after which the service cancels the task. A typical document takes no more than 5 seconds, and Processing Time Limit lists the endpoints with the limit.

  1. Send fewer records per request: split a large mergeData array into several requests, and send no more than two of them at a time, as Merge Requests Return 403 While Quota Is Left explains.
  2. Reduce the size of the template.
  3. Store a template you merge often in the template storage and merge it by templateName, so that it isn't transferred with each request.

Documents Have a Watermark

The documents that ReportingCloud returns carry a watermark or a logo. There are two reasons:

  • The account is a trial account. A document created with a trial account carries the ReportingCloud logo at the top left of the page, also when the request isn't a test run.
  • The request is a test request. The documents of a request with test=true contain a "TEST MODE" watermark, as Test Mode describes.

To create documents without either:

  1. Remove the parameter test from requests whose documents you deliver, or set it to false. With the PHP SDK, also check the option test of the ReportingCloud object, which adds the parameter to every request.
  2. On a trial account, add a subscription, as Upgrading to a Subscription describes.

Test Mode Isn't Available on a Free Account

You develop on a Free account and want to send requests that don't count against the document quota.

The parameter test of POST /v1/document/merge, POST /v1/document/append, POST /v1/document/convert and POST /v1/document/findandreplace can't be used with a Free account. On this account, every document request counts against the document quota.

A trial account can use test mode, and a test run returns a document with a "TEST MODE" watermark. On a trial account, a test run of document/convert and document/append is not counted against the document quota, while a test run of document/merge and document/findandreplace is.

  1. On a Free account, send requests without test, and keep an eye on createdDocuments while you develop.
  2. To test without using up the quota, add a subscription, as Upgrading to a Subscription describes.

The Trial Doesn't Create PDF/A

You request the return format PDFA from a trial account, and the request returns 403 Forbidden with the message Setting is not supported in this license. An Extreme license is required.

A trial account can't create PDF/A, the archiving format that the return format PDFA of POST /v1/document/merge, POST /v1/document/append, POST /v1/document/convert and POST /v1/document/findandreplace stands for.

  1. Use PDF as the return format while you evaluate the service.
  2. Before you rely on PDF/A, check which plan includes it: the price list in Plans and Licensing marks PDF/A for the Extreme plan only. Add that subscription as Upgrading to a Subscription describes.

Related Pages