Table of Contents

Struct RateLimitInfo

Namespace
RateLimitHeaders.Parsing
Assembly
RateLimitHeaders.dll

Represents parsed IETF RateLimit header information.

public readonly record struct RateLimitInfo : IEquatable<RateLimitInfo>
Implements
Inherited Members

Examples

Accessing rate limit info from a response context:

var context = ResilienceContextPool.Shared.Get();
try
{
    var response = await pipeline.ExecuteAsync(
        async (ctx) => await httpClient.GetAsync("https://api.example.com/v1/data"),
        context);

    if (context.Properties.TryGetValue(RateLimitContextProperties.RateLimitInfoKey, out RateLimitInfo info))
    {
        Console.WriteLine($"Rate limit: {info.Remaining}/{info.Quota}");
        Console.WriteLine($"Resets in: {info.ResetSeconds} seconds");

        if (info.IsQuotaLow(0.2))
        {
            Console.WriteLine("Warning: Quota is below 20%!");
        }
    }
}
finally
{
    ResilienceContextPool.Shared.Return(context);
}

Remarks

This is a readonly record struct that is safe to use with default initialization. When default-initialized, IsValid will be false and PolicyName will be an empty string.

Properties

IsValid

Whether at least one header was successfully parsed.

public bool IsValid { get; init; }

Property Value

bool

PartitionKey

The partition key identifying which partition this rate limit applies to.

public string? PartitionKey { get; init; }

Property Value

string

Remarks

Optional IETF parameter (pk). Used when rate limits are partitioned by different keys such as tenant ID, API key, or user ID. May be null if not provided by the server.

PolicyName

The rate limit policy name (e.g., "default", "api-v2").

public string PolicyName { get; init; }

Property Value

string

Remarks

Returns an empty string if no policy name was parsed.

Quota

Maximum requests allowed per window (quota).

public int Quota { get; init; }

Property Value

int

QuotaUnit

The unit of measurement for the quota (e.g., "requests", "content-bytes").

public string? QuotaUnit { get; init; }

Property Value

string

Remarks

Optional IETF parameter (qu). Default is "requests" when not specified. Common values include:

  • requestsNumber of API requests
  • content-bytesTotal bytes in request/response body
  • tokensToken count (for AI/ML APIs)

Remaining

Remaining requests allowed in the current window.

public int Remaining { get; init; }

Property Value

int

ResetSeconds

Seconds until the current window resets.

public int ResetSeconds { get; init; }

Property Value

int

WindowSeconds

Duration of the rate limit window in seconds.

public int WindowSeconds { get; init; }

Property Value

int

Methods

CreateFromRetryAfter(int)

Creates a minimal RateLimitInfo from a Retry-After header value.

public static RateLimitInfo CreateFromRetryAfter(int retryAfterSeconds)

Parameters

retryAfterSeconds int

The number of seconds from the Retry-After header.

Returns

RateLimitInfo

A valid RateLimitInfo with zero remaining quota.

Remarks

This is used when a 429/503 response includes a Retry-After header but no RateLimit headers. The resulting info indicates the client should wait before retrying.

GetRemainingPercentage()

Gets the remaining quota as a percentage (0.0 to 1.0).

public double GetRemainingPercentage()

Returns

double

IsQuotaLow(double)

Checks if remaining quota is at or below the specified threshold.

public bool IsQuotaLow(double threshold = 0.1)

Parameters

threshold double

The threshold percentage (0.0 to 1.0). Default is 0.1 (10%).

Returns

bool

True if quota is low; false otherwise.

ToString()

Returns the fully qualified type name of this instance.

public override string ToString()

Returns

string

The fully qualified type name.

WithRetryAfterOverride(int)

Creates a new RateLimitInfo with the Retry-After override applied.

public RateLimitInfo WithRetryAfterOverride(int retryAfterSeconds)

Parameters

retryAfterSeconds int

The Retry-After seconds that override the reset time.

Returns

RateLimitInfo

A new instance with Remaining set to 0 and ResetSeconds updated.

Remarks

Per IETF spec, Retry-After takes precedence over RateLimit headers when present. This typically occurs on 429/503 responses where the server explicitly tells the client how long to wait.

Edit this page