{"id":13998,"library":"serverless-api-gateway-throttling","title":"Serverless API Gateway Throttling Plugin","description":"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.","status":"active","version":"2.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/DianaIonita/serverless-api-gateway-throttling","tags":["javascript","serverless","aws","api","gateway","rest","request","throttling"],"install":[{"cmd":"npm install serverless-api-gateway-throttling","lang":"bash","label":"npm"},{"cmd":"yarn add serverless-api-gateway-throttling","lang":"bash","label":"yarn"},{"cmd":"pnpm add serverless-api-gateway-throttling","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This plugin extends the Serverless framework, requiring a compatible version for core functionality and configuration validation.","package":"serverless","optional":false}],"imports":[{"note":"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.","wrong":"plugins: serverless-api-gateway-throttling","symbol":"serverless-api-gateway-throttling","correct":"plugins:\n  - serverless-api-gateway-throttling"},{"note":"Global stage-level throttling settings are configured under the 'custom' section in 'serverless.yml'. These settings apply to all endpoints unless specifically overridden.","wrong":"provider:\n  apiGatewayThrottling: ...","symbol":"custom.apiGatewayThrottling","correct":"custom:\n  apiGatewayThrottling:\n    maxRequestsPerSecond: 1000\n    maxConcurrentRequests: 500"},{"note":"Endpoint-specific throttling settings are applied within the 'http' or 'httpApi' event definition for each function. Use 'throttling' as the key, not 'throttle'.","wrong":"events:\n  - http:\n      path: /item\n      method: post\n      throttle: ...","symbol":"http.throttling","correct":"events:\n  - http:\n      path: /item\n      method: post\n      throttling:\n        maxRequestsPerSecond: 2000\n        maxConcurrentRequests: 1000"}],"quickstart":{"code":"plugins:\n  - serverless-api-gateway-throttling\n\ncustom:\n  apiGatewayThrottling:\n    maxRequestsPerSecond: 1000\n    maxConcurrentRequests: 500\n\nfunctions:\n  # Throttling settings are inherited from stage settings\n  update-item:\n    handler: rest_api/item/post/handler.handle\n    events:\n      - http:\n          path: /item\n          method: post\n\n  # Requests are throttled using this endpoint's throttling configuration\n  list-all-items:\n    handler: rest_api/items/get/handler.handle\n    events:\n      - http:\n          path: /items\n          method: get\n          throttling:\n            maxRequestsPerSecond: 2000\n            maxConcurrentRequests: 1000\n\n  # Throttling is disabled for this endpoint\n  list-more-items:\n    handler: rest_api/items/get/handler.handle\n    events:\n      - http:\n          path: /more-items\n          method: get\n          throttling:\n            disabled: true\n  \n  # Supports httpApi (API Gateway v2)\n  list-http-api-items:\n    handler: rest_api/items/get/handler.handle\n    events:\n      - httpApi:\n          path: /http-api-items\n          method: get\n          throttling:\n            maxRequestsPerSecond: 3000\n            maxConcurrentRequests: 1000","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade your Serverless framework to version 2.11.1 or newer by running `npm install -g serverless`.","message":"Version 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.","severity":"breaking","affected_versions":"<1.0.2"},{"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`.","message":"Major 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.","severity":"breaking","affected_versions":"<2.0.0"},{"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.","message":"If 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"API 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'2.0.0':68 '2.0.3':40 'account':83 'account-level':82 'activ':43 'addit':58 'address':74 'allow':104 'also':133 'api':2,8,23,61,62,80,91,114,117,130,147 'aw':146 'bug':49 'cadenc':45 'cli':136 'command':137 'common':76 'configur':22 'control':128 'current':36 'custom':108 'default':79 'design':18 'develop':105 'differenti':71 'easili':139 'endpoint':33,142 'enhanc':53 'exhaust':98 'featur':52 'fine':126 'fine-grain':125 'fix':50 'framework':17 'gateway':3,9,24,63,81,148 'grain':127 'http':60,116 'impact':89 'includ':47 'individu':32 'inherit':120 'javascript':144 'lead':96 'level':34,84 'limit':86 'major':57 'manag':20 'maxconcurrentrequest':111 'maxrequestspersecond':109 'method':102 'offer':124 'overrid':118 'pitfal':77 'plugin':5,13,70 'potenti':95 'provid':134 'region':94 'regular':48 'releas':44 'request':150 'reset':140 'rest':113,149 'serverless':1,7,16,145 'serverless-api-gateway-throttl':6 'set':26,122,143 'singl':101 'specifi':107 'stabl':37 'stage':30,121 'support':65 'throttl':4,10,25,85,151 'traffic':131 'unintent':88 'v2':64 'version':38,67","created_at":"2026-04-20T01:57:24.108322+00:00","updated_at":"2026-04-20T01:57:24.108322+00:00","problems":[{"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.","cause":"This error specifically affects ApiGatewayV2 (HTTP) throttling configurations, where the plugin could not correctly identify or associate a route for applying settings.","error":"Error: 'Unable to find Route by key within route settings'"},{"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.","cause":"An issue where the plugin would cause deployment to fail if the CloudFormation stack had not yet been created for the service.","error":"Deployment failure when stack does not exist."},{"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.","cause":"When configuring HTTP API endpoints, deployments could fail if the plugin was unable to locate the associated HTTP API resource.","error":"Deployment failure because a Http API was not found."},{"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.","cause":"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.","error":"Throttling settings were not inherited from stage settings when endpoint configuration was not defined."},{"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.","cause":"Manually changing many endpoint settings can be cumbersome, and you may want to revert them to stage defaults without manual removal.","error":"How do I reset all endpoint-specific throttling settings to inherit from the stage again?"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"serverless","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/DianaIonita/serverless-api-gateway-throttling","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/serverless-api-gateway-throttling","openapi_spec":null,"status_page":null,"smithery":null,"categories":["aws","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}