Rate limits

Use this page to keep the API calls of your app below the limits of Wafeq ASP. It also tells you what to do when your app goes above a limit.

This page uses these terms:

• Your organization: the account of your company in the Wafeq ASP portal. Your company builds the app that uses the Wafeq ASP API. Your API keys and your OAuth client belong to your organization.
• Your app: the software that your company builds.
• Mode: Live or Sandbox. Live is real e-invoicing. Sandbox is for tests.
• Path: the part of the URL after the base URL https://api.wafeq.com/ae/v1. For example, the path of https://api.wafeq.com/ae/v1/invoices is /invoices.
• Rate limit: the maximum number of requests that Wafeq ASP accepts on one path in one minute.
• Document ID: the ID that Wafeq ASP gives a document when it accepts it (document_id). Some paths contain it.
• Peppol: the network that UAE businesses use to exchange e-invoices.
• Idempotency-Key: the header that makes a submission safe to repeat. Refer to Submit a document.

The limits

Wafeq ASP applies these limits in Live and in Sandbox. Each row gives the limit of each path in that row. The table does not give one total for the whole API.

For the stages in which your app uses these calls, refer to Submit a document (stage 3) and Track a document (stage 4).

How Wafeq ASP counts requests

• Per organization. When a request has a valid API key or access token, Wafeq ASP counts it for your organization. All your API keys, tokens and taxpayers share one count for each path. A new API key does not give a new allowance.
• Per IP address. Wafeq ASP counts all other requests per IP address. For example, the requests to the paths that start with /oauth/ authenticate with a client ID and client secret. Thus they count per IP address.
• Per mode. Live and Sandbox count separately.
• Per path. Each path has its own count. A path that contains a document ID is a different path for each document. For example, GET /invoices/inv_A and GET /invoices/inv_B count separately. The query string is not part of the path.
• Per limit. Two methods on the same path share one count when they have the same limit. For example, GET and PATCH on the same /invoices/{document_id} share 120 requests per minute. GET /invoices and POST /invoices have different limits. Thus they count separately.

Recover from a 429 response: the three steps

When your app goes above a limit, Wafeq ASP answers 429 Too Many Requests. Wafeq ASP does not process the request. The response body gives the limit, for example:

{ "error": "Rate limit exceeded: 60 per 1 minute" }

The response has no Retry-After header and no headers that give the remaining requests. Do not make your app depend on these headers.

Step 1: Stop the requests to that path

Stop the requests to the path that got the 429. Each path has its own count. Thus your app can continue to call the other paths.

Step 2: Wait, with exponential backoff and jitter

Wait before the next attempt. Make each wait longer than the wait before it. Add a random part to each wait, so that your servers do not send their requests at the same time.

Step 3: Send the same request again

Send the request again without changes.

For a submission, use the same Idempotency-Key. Wafeq ASP did not accept the document. With the same key, Wafeq ASP cannot accept the document two times, also if your app sends the request more than one time. Never make a new key to retry a submission.

How Wafeq ASP applies the limits at this time

This section is not a step. It tells you how the limits work now. Do not make your app depend on these details.

• Wafeq ASP counts requests in fixed windows of one minute.
• Each server process of Wafeq ASP keeps its own count. Thus your app can sometimes send more requests than the table shows before it gets a 429.
• The paths that are not in the table have no limit at this time. For example, GET /taxpayers and GET /grants have no limit.