diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/ratelimiting.md | 27 | ||||
| -rw-r--r-- | docs/api/swagger.md | 11 | ||||
| -rw-r--r-- | docs/configuration/advanced.md | 17 |
3 files changed, 44 insertions, 11 deletions
diff --git a/docs/api/ratelimiting.md b/docs/api/ratelimiting.md new file mode 100644 index 000000000..88e6ce56c --- /dev/null +++ b/docs/api/ratelimiting.md @@ -0,0 +1,27 @@ +# Rate Limit + +To mitigate abuse + scraping of your instance, an IP-based HTTP rate limit is in place. + +This rate limit applies not just to the API, but to all requests (web, federation, etc). + +By default, a maximum of 1000 requests in a 5 minute time window are allowed. + +Every response will include the current status of the rate limit with the following headers: + +- `X-Ratelimit-Limit`: maximum number of requests allowed per time period. +- `X-Ratelimit-Remaining`: number of remaining requests that can still be performed within. +- `X-Ratelimit-Reset`: unix timestamp indicating when the rate limit will reset. + +In case the rate limit is exceeded, an [HTTP 429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) error is returned to the caller. + +## Rate Limiting FAQs + +### My rate limit keeps being exceeded! Why? + +If you find that your rate limit is regularly being exceeded (both for yourself and other callers) during normal use of your instance, it's possible that your `trusted-proxies` setting is not configured correctly. This can result in your instance seeing all incoming IP addresses as the same address: namely, the IP address of your reverse proxy. This means that all incoming requests are *sharing the same rate limit*, rather than being split correctly per IP. + +You can investigate this by viewing the logs of your instance. If (almost) all logged IP addresses appear to be the same IP address (something like `172.x.x.x`), then it's likely that your `trusted-proxies` is not correctly configured. If this is the case, try adding the IP address of your reverse proxy to the list of `trusted-proxies`, and restarting your instance. + +### Can I configure the rate limit? Can I just turn it off? + +Yes! See the config setting `advanced-rate-limit-requests`. diff --git a/docs/api/swagger.md b/docs/api/swagger.md index fac2ba009..50191f18d 100644 --- a/docs/api/swagger.md +++ b/docs/api/swagger.md @@ -1,16 +1,5 @@ # API Documentation -## Rate limit - -To prevent abuse of the API an IP-based HTTP rate limit is in place, a maximum of 1000 requests in a 5 minutes time window are allowed, every response will include the current status of the rate limit with the following headers: - -- `x-ratelimit-limit` maximum number of requests allowed per time period (fixed) -- `x-ratelimit-remaining` number of remaining requests that can still be performed -- `x-ratelimit-reset` unix timestamp when the rate limit will reset - -In case the rate limit is exceeded an HTTP 429 error is returned to the caller. - - GoToSocial uses [go-swagger](https://github.com/go-swagger/go-swagger) to generate a V2 [OpenAPI specification](https://swagger.io/specification/v2/) document from code annotations. The resulting API documentation is rendered below, for quick reference. diff --git a/docs/configuration/advanced.md b/docs/configuration/advanced.md index 48b1b569d..f4b8c5ffa 100644 --- a/docs/configuration/advanced.md +++ b/docs/configuration/advanced.md @@ -35,4 +35,21 @@ These are set to sensible defaults, so most server admins won't need to touch th # Options: ["lax", "strict"] # Default: "lax" advanced-cookies-samesite: "lax" + +# Int. Amount of requests to permit from a single IP address within a span of 5 minutes. +# If this amount is exceeded, a 429 HTTP error code will be returned. +# See https://docs.gotosocial.org/en/latest/api/swagger/#rate-limit. +# +# If you find yourself adjusting this limit because it's regularly being exceeded, +# you should first verify that your settings for `trusted-proxies` (above) are correct. +# In many cases, when the rate limit is exceeded it is because your instance sees all +# incoming requests as coming from the *same IP address* (you can verify this by looking +# at the client IPs in your instance logs). If this is the case, try adding that IP +# address to your `trusted-proxies` *BEFORE* you go adjusting this rate limit setting! +# +# If you set this to 0 or less, rate limiting will be disabled entirely. +# +# Examples: [1000, 500, 0] +# Default: 1000 +advanced-rate-limit-requests: 1000 ``` |