Registry / aws / serverless-api-gateway-throttling

serverless-api-gateway-throttling

JSON →
library2.0.3jsnpmunverified

serverless-api-gateway-throttling is a plugin for the Serverless framework designed to manage and configure API Gateway throttling settings at both the stage and individual endpoint levels. Its current stable version is 2.0.3, with an active release cadence that includes regular bug fixes and feature enhancements, such as the major addition of HTTP API (API Gateway v2) support in version 2.0.0. This plugin differentiates itself by addressing a common pitfall where default API Gateway account-level throttling limits can unintentionally impact all APIs in a region, potentially leading to exhaustion by a single method. It allows developers to specify custom maxRequestsPerSecond and maxConcurrentRequests for REST APIs and HTTP APIs, overriding the inherited stage settings and offering fine-grained control over API traffic. It also provides a CLI command to easily reset all endpoint settings.

awsdevops
npm install serverless-api-gateway-throttling
github ↗package ↗
INSTALL
IMPORT
SIG · SERVERLESS-API-GAT
S
serverless-api-gateway-throttling
awsjavascriptv2.0.3
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

serverless-api-gateway-throttling
✓ plugins: - serverless-api-gateway-throttling
✗ plugins: serverless-api-gateway-throttling
The plugin is enabled by listing its npm package name in the 'plugins' array within your 'serverless.yml' configuration file. Ensure correct YAML list syntax.
custom.apiGatewayThrottling
✓ custom: apiGatewayThrottling: maxRequestsPerSecond: 1000 maxConcurrentRequests: 500
✗ provider: apiGatewayThrottling: ...
Global stage-level throttling settings are configured under the 'custom' section in 'serverless.yml'. These settings apply to all endpoints unless specifically overridden.
http.throttling
✓ events: - http: path: /item method: post throttling: maxRequestsPerSecond: 2000 maxConcurrentRequests: 1000
✗ events: - http: path: /item method: post throttle: ...
Endpoint-specific throttling settings are applied within the 'http' or 'httpApi' event definition for each function. Use 'throttling' as the key, not 'throttle'.

This 'serverless.yml' configuration snippet demonstrates how to enable the plugin, set global stage-level throttling, override settings for specific REST API endpoints, disable throttling for an endpoint, and configure throttling for HTTP API (v2) endpoints. Although the language is specified as 'javascript', this example provides the YAML configuration directly.

plugins: - serverless-api-gateway-throttling custom: apiGatewayThrottling: maxRequestsPerSecond: 1000 maxConcurrentRequests: 500 functions: # Throttling settings are inherited from stage settings update-item: handler: rest_api/item/post/handler.handle events: - http: path: /item method: post # Requests are throttled using this endpoint's throttling configuration list-all-items: handler: rest_api/items/get/handler.handle events: - http: path: /items method: get throttling: maxRequestsPerSecond: 2000 maxConcurrentRequests: 1000 # Throttling is disabled for this endpoint list-more-items: handler: rest_api/items/get/handler.handle events: - http: path: /more-items method: get throttling: disabled: true # Supports httpApi (API Gateway v2) list-http-api-items: handler: rest_api/items/get/handler.handle events: - httpApi: path: /http-api-items method: get throttling: maxRequestsPerSecond: 3000 maxConcurrentRequests: 1000
serverless --version
Debug
Known issues
breakingVersion 1.0.2 introduced configuration validation which requires Serverless framework version 2.11.1 or later. Deployments with older Serverless versions may fail due to schema validation errors.
fix
Upgrade your Serverless framework to version 2.11.1 or newer by running `npm install -g serverless`.
affects: <1.0.2
breakingMajor version 2.0.0 added full support for HTTP APIs (API Gateway v2). While this is a new feature, attempting to configure HTTP API throttling prior to this version would not have worked, leading to unexpected behavior or ignored settings.
fix
Ensure you are using `serverless-api-gateway-throttling` version 2.0.0 or greater when configuring throttling for HTTP API endpoints. Update your plugin via `npm install serverless-api-gateway-throttling@latest`.
affects: <2.0.0
gotchaIf custom throttling settings are defined for an endpoint with the HTTP method `ANY`, these settings will be applied to all standard HTTP methods (GET, DELETE, HEAD, OPTIONS, PATCH, POST, PUT) for that specific path.
fix
Be mindful of the `ANY` method's behavior; if you need different throttling for specific methods under the same path, define them individually instead of relying solely on `ANY` with custom throttling.
affects: >=1.0.0
gotchaAPI Gateway's default throttling is an account-level limit (e.g., 10,000 requests/second with 5000 burst), which can be exhausted by a single API or endpoint, affecting all APIs in the region. This plugin is designed to prevent this by allowing per-endpoint limits.
fix
Always define `apiGatewayThrottling` settings, either globally at the stage level or specifically per endpoint, to override the restrictive account-level defaults and protect your APIs from resource starvation.
affects: >=1.0.0
Errors
Common errors & fixes
Error: 'Unable to find Route by key within route settings'
This error specifically affects ApiGatewayV2 (HTTP) throttling configurations, where the plugin could not correctly identify or associate a route for applying settings.
fix
Upgrade to version 2.0.3 or newer of the plugin (`npm install serverless-api-gateway-throttling@latest`), which includes a fix for this routing issue.
Deployment failure when stack does not exist.
An issue where the plugin would cause deployment to fail if the CloudFormation stack had not yet been created for the service.
fix
Upgrade to version 2.0.2 or newer (`npm install serverless-api-gateway-throttling@latest`). This version includes a fix to handle deployments gracefully when the stack is initially being created.
Deployment failure because a Http API was not found.
When configuring HTTP API endpoints, deployments could fail if the plugin was unable to locate the associated HTTP API resource.
fix
Upgrade to version 2.0.1 or newer (`npm install serverless-api-gateway-throttling@latest`) to resolve issues with HTTP API resource lookup during deployment.
Throttling settings were not inherited from stage settings when endpoint configuration was not defined.
An earlier bug (Issue #5) prevented endpoints from correctly inheriting global stage-level throttling settings if no explicit throttling configuration was provided for that endpoint.
fix
Upgrade to version 1.1.0 or newer (`npm install serverless-api-gateway-throttling@latest`) to ensure proper inheritance of stage-level throttling settings.
How do I reset all endpoint-specific throttling settings to inherit from the stage again?
Manually changing many endpoint settings can be cumbersome, and you may want to revert them to stage defaults without manual removal.
fix
Execute the command `sls reset-all-endpoint-settings` from your project root. This command will clear all custom endpoint settings, allowing them to inherit from the stage configuration again.
Upgrade
Version history
2.0.3latest on npm
Audit
Dependencies
serverlessrequiredThis plugin extends the Serverless framework, requiring a compatible version for core functionality and configuration validation.
Agent activity
12 hits · last 30 days
node
12
Resources
githubhttps://github.com/DianaIonita/serverless-api-gateway-throttling ↗
packagehttps://www.npmjs.com/package/serverless-api-gateway-throttling ↗