Royal Mail operates under industry standard protocols on API utilisation to protect our customers, customer data and systems. 

Why do we have throttling plans?

When API consumption reaches levels that could put customer information or our systems at risk, throttling is a safeguard that ensures stability. By protecting the integrity of our systems, we protect our customers’ ability to operate without disruption

It is an industry‑standard practice used across the technology sector with respect to APIs to maintain security, resilience, and service continuity. Our goal is always to keep customers at the centre of every decision we make, and throttling is one of the ways we ensure their data remains secure and our platforms remain dependable

1. Rate limits defined per plan

• Each API plan includes a rate limit specifying the maximum number of requests allowed during a specific time period. Some plans apply a single limit across all included API resources, while others may set different limits per resource.
• Some APIs may have both Plan Limits and Burst Limits.
• Burst Limits are throttling rules set for short intervals like 5-10 seconds and will generally reside over a plan limit which can have hourly or daily interval.

Example: An API Consumer is allowed 200000 requests per day ( plan limit ) but the consumption cannot exceed 100 requests in 5 seconds ( burst limit)
 

2. Throttling applies when limits are exceeded

If your application exceeds its allocated limit, the API will respond with 429 HTTP Error code for additional requests until the window resets. This behaviour is consistent with standard API rate-limiting practices adopted across API industry inline with REST best practices.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429

• Do Royal Mail APIs throttle usage? - Yes
• How is throttling enforced? - Through API plans with fixed rate limits
• Are limits global or per-endpoint? - Depends on the plan
• Where can you see your exact limits? -Under your Subscriptions or under Product Definition
  If you require higher limits to be set for your subscription kindly reach out to your RMG technical contact.

The numbers of requests, for different APIs, that your application has made are shown on your application page.

Click 'Apps' in the main menu and then click on your application. In the 'Product Subscriptions' table you will see all plans your application is subscribed to.

For each API contained in that plan you can see the usage compared to the rate limit of the plan.

It is possible to test an API from this Developer Portal.

When looking at the details of an API you will see a list of the operations contained in the API. This will show the verb and path to use for the operation.

If you click on the operation you will see more information about it, what parameters it might take, what it returns, what possible return codes it might use and what they mean.

There is also a 'Try' button on REST APIs which enables you to try the operation out direct from the Developer Portal.

If the API requires a client ID or a client secret for identification then you can specify these using your application credentials at the top of the 'Try' section.

When you add an application you are provided with an API Key and Secret for the application. You must supply these credentials when you call an API that requires you to authenticate your application.

To register an application click on Apps in the main menu and then click on the 'Create new app' link. Once you have provided an application name, description, etc you will be shown your application API Key and Secret.

Make a note of your API Secret because it is only displayed once.

Your API Secret is stored encrypted so we cannot retrieve the unencrypted version to tell you the value if you forget it.

You can reset it, which will update the stored value and return the new value to you.

To do that click 'Apps' in the main menu, click on the application in question and then you can click the 'Reset' link in the 'API Secret' section.

Your new Secret will be displayed at the top of the page.