Skip to content
Tutorials Center
My learning

Topics

Lesson 40 of 52 ยท Advanced Topics

Rate Limiting, Health Checks and Resilience of the App

Protect an ASP.NET Core app with rate limiter policies, request timeouts and health check endpoints for liveness and readiness, with runnable examples.

The previous lesson was about your calls to other services failing. This one is about the opposite problem: other people's traffic hurting you. A bug in a client that retries in a tight loop, a scraper, a sudden spike or a single expensive endpoint can take down an application that works perfectly under normal load. Three built-in features protect you: rate limiting (say no politely when someone asks too often), request timeouts (stop work that takes too long) and health checks (tell your platform whether the app is alive and ready for traffic).

All three ship in the ASP.NET Core shared framework, so every example below runs live. If you want to see how callers should react to the 429 and 503 answers these features produce, read Calling Other Services: HttpClient and Resilience.

Rate limiting

A rate limiter decides, for each incoming request, whether it may proceed. If not, the middleware answers immediately (by default with status 503, which you should change to 429 Too Many Requests) and your endpoint code never runs. That makes rejection cheap, which is exactly what you want under pressure.

The framework offers four built-in algorithms:

Algorithm Idea Good for
Fixed window N requests per time window; the counter resets at each boundary simple quotas
Sliding window like fixed, but the window slides in segments, avoiding boundary bursts smoother quotas
Token bucket tokens refill at a steady rate; each request takes one; bursts allowed up to bucket size allowing short bursts
Concurrency at most N requests running at the same time protecting slow or expensive work
flowchart LR
    A["Request"] --> B{"Rate limiter<br/>permit available?"}
    B -->|"yes"| C["Endpoint runs"]
    B -->|"no, queue has room"| D["Wait in queue"]
    D --> B
    B -->|"no"| E["429 Too Many Requests<br/>Retry-After header"]

A rejected request never reaches your endpoint code, so rejection is cheap.

You set the limiter up in two places: builder.Services.AddRateLimiter(...) defines policies, and app.UseRateLimiter() adds the middleware. The next program uses a fixed window of three requests per minute and returns a helpful Retry-After header when it rejects.

C# A fixed window rate limiter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

The first three requests pass, the next two are rejected with 429 and a Retry-After, and /about never notices because it does not name the policy. You can apply a policy to a whole group with RequireRateLimiting on a MapGroup, and exempt one endpoint with DisableRateLimiting(). options.GlobalLimiter sets a limiter that applies to every request.

Setting QueueLimit above zero makes extra requests wait for a permit instead of being rejected, up to the queue size. Queues smooth short spikes, but each waiting request holds a connection open, so keep them small and never queue unbounded.

Partitioning: limits per client

One shared limit means a single noisy client can use up everyone's quota. Usually you want a separate counter per client: per IP address, per API key or per signed-in user. In ASP.NET Core this is a partitioned limiter: you compute a partition key from the request, and each distinct key gets its own limiter instance.

You create one with options.AddPolicy("name", httpContext => RateLimitPartition.GetFixedWindowLimiter(key, _ => new FixedWindowRateLimiterOptions { ... })). The lambda returns a partition for this request; requests with the same key share a limiter.

C# A rate limit per client

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Alice's third request is rejected while Bob is untouched, because each name has its own counter. The concurrency limiter in the second half is a different tool: it does not count requests per time, it counts how many are in flight, which is the right protection for a slow endpoint such as a report or an export.

Picking the partition key is the hard part. The client's IP address (context.Connection.RemoteIpAddress) is simple, but behind a reverse proxy it is the proxy's address unless forwarded headers are configured, and many users can share one address. Per-user keys after authentication are fairer. Limiter state lives in memory of one server, so with several servers each one counts separately; shared quotas need a gateway or a distributed store.

Request timeouts

A request that takes forever ties up a connection and server resources. The request timeouts middleware (AddRequestTimeouts, UseRequestTimeouts) gives each endpoint a time budget. When it runs out, HttpContext.RequestAborted is cancelled, so any code that passes that token to Task.Delay, database calls or outgoing HttpClient calls stops, and the middleware answers with 504 Gateway Timeout if nothing has been sent yet. Handlers must cooperate by honoring the token: code that ignores it keeps running.

C# A timeout policy for slow endpoints

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

You can also set a DefaultPolicy for every endpoint and use [DisableRequestTimeout] or .DisableRequestTimeout() for endpoints that legitimately run long, such as streaming or file uploads. Request timeouts are disabled while a debugger is attached, so do not be surprised when they do not fire during debugging.

Health checks

Platforms need a cheap way to ask an application "are you OK?". Kubernetes, load balancers, Docker and uptime monitors all poll an HTTP endpoint and act on the status code. ASP.NET Core's health checks provide that endpoint and let you plug in custom tests.

Two different questions matter, and mixing them up causes outages:

  • Liveness: "is the process running and not wedged?" A failing liveness check means the platform should restart the app. It must be cheap and must not depend on other services; otherwise a database outage makes the platform restart every healthy web server in a loop.
  • Readiness: "can this instance serve traffic right now?" A failing readiness check means the platform should stop sending requests to this instance (but not kill it). This is where you check the database, the cache and other dependencies.
flowchart TD
    P["Platform / load balancer"] -->|"GET /health/live"| L["Liveness: process responds"]
    P -->|"GET /health/ready"| R["Readiness: database, cache, ..."]
    L -->|"fails"| X["Restart the instance"]
    R -->|"fails"| Y["Remove from rotation,<br/>do not restart"]

Liveness decides whether to restart; readiness decides whether to route traffic.

A health check returns Healthy, Degraded or Unhealthy. By default Healthy and Degraded answer 200 and Unhealthy answers 503. You write your own check by implementing IHealthCheck, register it with AddHealthChecks().AddCheck<T>(name, tags: [...]), and use tags plus the Predicate option on MapHealthChecks to decide which checks each endpoint runs.

C# Liveness and readiness endpoints

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Look at the three states. While the database is down, /health/live still answers 200 (the process is fine, so no restart), and /health/ready answers 503 (take this instance out of rotation until the database returns). A degraded dependency keeps the default 200 but reports the problem in the body, which is useful for dashboards.

Practical advice for health endpoints:

  • Keep checks fast and give each a timeout; a check that hangs makes the endpoint hang.
  • Do not expose detailed reports to the public internet; they reveal internals. Return only the status code externally, and detailed JSON on an internal port or behind authorization.
  • Health endpoints are usually exempt from authentication and rate limiting, so platform probes always get an answer.
  • You can run a check on a schedule and publish results through IHealthCheckPublisher instead of at request time when a check is expensive.

Graceful shutdown

Resilience also means ending well. When the platform sends a stop signal during a deployment, ASP.NET Core stops accepting new connections, gives running requests time to finish (the host ShutdownTimeout, 30 seconds by default in .NET 10), and then stops. Pair this with readiness: once shutdown begins, report not-ready so the load balancer stops sending new traffic. The earlier lesson Background Services and Hosted Services shows how long-running work cooperates with the stop signal.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which status code should a rate limiter normally answer with for a rejected request?

    429 tells the client it is sending too many requests and should slow down. The framework default is 503, so you set RejectionStatusCode explicitly.
  2. 2. Why partition a rate limiter by client (for example by API key)?

    A partitioned limiter gives each key its own counter, so one heavy caller is limited without affecting well-behaved callers.
  3. 3. Your database is down. What should the liveness and readiness endpoints report?

    Restarting every instance does not fix a database outage. Liveness stays healthy so nothing is restarted, while failing readiness removes the instance from traffic until the dependency recovers.
  4. 4. What makes a request timeout actually stop a slow handler?

    The timeout cancels RequestAborted. Code that passes the token on (Task.Delay, database and HTTP calls) is interrupted; code that ignores it keeps running.

Summary

  • AddRateLimiter plus UseRateLimiter rejects excess traffic before your endpoint runs; apply policies with RequireRateLimiting and set RejectionStatusCode to 429.
  • Choose fixed window, sliding window, token bucket or concurrency limiters, and partition by client so one caller cannot starve the rest.
  • Limiter state is per server process; shared quotas need infrastructure outside the app.
  • AddRequestTimeouts gives endpoints a time budget by cancelling RequestAborted; handlers must pass the token on.
  • Health checks return Healthy, Degraded or Unhealthy; liveness decides restarts, readiness decides traffic, and tags with Predicate separate them.
  • Keep health checks fast, keep detailed reports private and let graceful shutdown finish in-flight requests.

Next: Testing ASP.NET Core Apps