Polly operates as a dedicated .NET library engineered to intercept transient faults and execute resilience patterns across distributed systems. When coupled with the Ocelot API gateway, it enables thread-safe execution of retry orchestration, circuitsolation, latency capping, response storage, and graceful degradation workflows.

Core Resilience Capabilities

• Adaptive Retry Sequencing
• Circuit Breaker Isolation
• Latency Threshold Enforcement
• In-Memory Response Caching
• Graceful Degradation Routing

Dependency Injection Registration

Initialize the resilience pipeline by extending your service container within the application startup phase. The following implementation demonstrates the registration sequence using alternative method naming and variable references while preserving framework compatibility:

public void InitializeGatewayPipeline(IServiceCollection container)
{
    container.AddOcelot();
    container.AddPollyIntegration();
}

Gateway Configuration Schema

Define threshold limits, cache lifecycles, and traffic shaping rules directly in the routing configuration. The structure below outlines a production-ready template with adjusted placeholder identifiers and refined nesting:

{
  "DownstreamPathTemplate": "/v1/catalog/items",
  "DownstreamScheme": "https",
  "DownstreamHostAndPorts": [
    {
      "Host": "inventory-service.internal",
      "Port": 443
    }
  ],
  "UpstreamPathTemplate": "/api/retrieve/products",
  "UpstreamHttpMethod": ["GET"],
  "FileCacheOptions": {
    "TtlSeconds": 25
  },
  "QoSOptions": {
    "ExceptionsAllowedBeforeBreaking": 4,
    "DurationOfBreak": 7000,
    "TimeoutValue": 1200
  },
  "RateLimitOptions": {
    "ClientWhitelist": ["audit-logger", "dashboard-svc"],
    "EnableRateLimiting": true,
    "Period": "5s",
    "PeriodTimespan": 2,
    "Limit": 8
  }
}

Parameter Mapping and Behavior

FileCacheOptions.TtlSeconds: Determines the persistence window for cached responses. Higher values reduce backend hit rates but increase memory consumption and potential stale data exposure.

QoSOptions.ExceptionsAllowedBeforeBreaking: Establishes the error accumulation threshold. Once consecutive failures reach this count, the circuit transitions to an open state. Requires pairing with DurationOfBreak.

QoSOptions.DurationOfBreak: Sets the cooling period in milliseconds where all routed requests are rejected immediately. Allows degraded services time to self-heal before half-open testing resumes.

QoSOptions.TimeoutValue: Caps the maximum dwell time awaiting a backend response. Connections exceeding this boundary are forcefully terminated. Note that Ocelot applies a 90-second baseline timeout by default, which often masks sluggish dependencies unless explicitly overridden.

Traffic Shaping Directives

ClientWhitelist: Array of identity strings granted exemption from throttling boundaries. Requests bearing matching identifiers bypass allocation checks entirely.

EnableRateLimiting: Master switch toggling the rate limiter middleware active or inactive.

Period: Calculation window formatted using standard duration syntax (s, m, h, d). Governs how request counters reset.

PeriodTimespan: Secondary delay interval in seconds applied after a limit breach before the throttled entity may resume transmission.

Limit: Maximum permitted invocations allowed with in a single Period window before subsequent calls are intercepted.

Advanced Header and Response Customization

Override default telemetry headers and error payloads at the global configuration layer for finer control over consumer interactions:

{
  "GlobalConfiguration": {
    "RateLimitOptions": {
      "DisableRateLimitHeaders": false,
      "QuotaExceededMessage": "Capacity threshold reached, please retry shortly",
      "HttpStatusCode": 429,
      "ClientIdHeader": "X-Tenant-Id"
    }
  }
}

DisableRateLimitHeaders: Toggles emission of standard tracking headers. Set to true to strip metadata from outbound responses.

QuotaExceededMessage: Replaces the default text embedded in the response body when allocations are exhausted.

HttpStatusCode: Assigns a specific HTTP integer to throttle events. Industry standards favor 429, though arbitrary codes remain functionally valid.

ClientIdHeader: Defines the request header name utilized to extract the unique requester identifier for quota mapping and whitelist validation.

Conforming specifications dictate that X-Rate-Limit communicates remaining allowance counts within the active window, while Retry-After specifies the mandatory pause duration prior to successful submission. Aligning these resilience boundaries with actual infrastructure capacity and traffic profiles prevents unnecessary cascading failures and ensures predictable gateway behavior under peak load conditions.