Rate limit

Purpose and importance

API call budgets define the number of API calls that an API client can make in a given amount of time and are a safeguard against runaway applications and malicious behavior. Call budgets (or rate limits) are a standard feature of high performance APIs across industries and working within the provided call budget is table stakes for any developer building an application that consumes the API. The best practice is for applications to manage API call budgets effectively and avoid making API calls in excess of the limit.

Per organization

Each Meraki organization has a call budget of 10 requests per second, regardless of the number of API applications interacting with that organization.

• A burst of 10 additional requests are allowed in the first second, yielding a maximum of 30 requests in the first 2 seconds.
• The rate limiting technique is based off of the token bucket model.

This budget is shared across all API applications in the organization that leverage API authentication. You can check the recent API activity for the given organization to understand if you are sharing the budget with other applications.

Per source IP address

Each source IP address making API requests has a call budget of 100 requests per second, regardless of the number of API clients working from that IP address.

Response codes

• A 429 status code will be returned when the rate limit has been exceeded, with the Retry-After header.
• When an application exceeds the rate limit, the following message will be returned in the response body:

{
    "errors": [
        "API rate limit exceeded for organization"
    ]
}

Best practices and tips for managing call budgets

Handle limiting gracefully

If the defined budget is exceeded, the dashboard API will reply with the 429 (rate limit exceeded) error code. This response also returns a Retry-After header indicating how long the client should wait before making a follow-up request. Ensure that appropriate action is being taken to handle 429 responses if you incur them. Utilize the Retry-After header and backoff to minimize compounded rate limit issues.

• The Retry-After header contains the number of seconds the client should wait.
• Expect to backoff for 1 - 2 seconds if the limit has been exceeded. You may have to wait potentially longer if a large number of requests were made within this timeframe.

If you are using Python, the official Meraki Python library handles retries and automatic backoff for you so you can focus elsewhere in your application.​

A simple Python script example which minimizes rate limit errors:

response = requests.request("GET", url, headers=headers)
​
if response.status_code == 200:
    # Success logic
elif response.status_code == 429:
    time.sleep(int(response.headers["Retry-After"]))
else:
    # Handle other response codes

Monitoring best practices

Strategize your data polling. The most common cause of 429 responses is unnecessarily frequent polling of information that changes infrequently after day 1 of a network deployment, such as the list of networks or policy objects in an organization.

Use the most efficient operations for your use case

Develop your application using the most efficient API calls available for your use case, especially if your application provides monitoring features.

Retrieving network topology information including LLDP/CDP

Call the network-wide getNetworkTopologyLinkLayer, which provides the complete topology for the network, instead of the less efficient single-device operation getDeviceLldpCdp.

Retrieving device uplink information (IP addressing)

Call the organization-wide getOrganizationDevicesUplinksAddressesByDevice instead of looking for IP information in per-device operations.

Retrieving device hardware details

Call the organization-wide getOrganizationDevices, which provides the information for hundreds devices at a time in a paginated list, instead of the less efficient single-device operation getDevice or the network-wide operation getNetworkDevices.

Monitoring device availability (status)

Call the organization-wide getOrganizationDevicesAvailabilitiesChangeHistory to catch up on availability (status) changes since your last org-wide poll of getOrganizationDevicesAvailabilities or getOrganizationDevicesStatuses, rather than re-polling the information for all devices all over again.

Retrieving network clients

Call the network-wide API call getNetworkClients once for the network, instead of calling the less efficient single-device API operation getDeviceClients.

Provisioning

Use action batches

Action Batches are a perfect tool for submitting batched configuration requests in a single synchronous or asynchronous transaction. Leverage them for bulk constructive/destructive operations (POST, PUT, DELETE). To read more about Action Batches, visit our overview, the GitHub Demo, or the Meraki Blog.

Configuration sync and "golden template" enforcement

Once you are confident that an organization is configured correctly, leverage getOrganizationConfigurationChanges to identify deviations from the last known intended configuration. This is more efficient than re-polling every configuration setting and then running diffs in your application.

Use configuration templates

Meraki configuration templates are an easy way to ensure a highly consistent configuration is deployed across networks.

Troubleshooting

If your application is rate limited, your application or another application in the organization, or from your application's source IP address, may not be managing the call budget effectively.

1. Ensure your application is following our best practices. If you are using an ecosystem partner application, our partners are committed to following our best practices. Please reach out to the developer for your application if you have any questions about partner application behavior or budget consumption.
2. You can check the recent API activity for the given organization to understand if you are sharing the budget with other applications.
3. Scripts that run with little to no maintenance can degrade the performance of your organization's API requests and use up your budget unnecessarily. Audit your organization's API consumption on a regular basis.

You can find more answers about call budgets in our developer community.