---
id: api-http-ratelimit-fields-and-structured-fields
title: 'API HTTP RateLimit Fields and Structured Fields'
schema_type: TechArticle
category: computer-science
language: en
confidence: medium
last_verified: '2026-06-09'
created_date: '2026-06-09'
generation_method: ai_structured
derived_from_human_seed: true
conflict_of_interest: none_declared
is_live_document: false
data_period: static
atomic_facts:
  - id: fact-cs-api-http-ratelimit-fields-and-structured-fields-1
    statement: >-
      RFC 9333 defines the HTTP RateLimit-Limit, RateLimit-Remaining, and
      RateLimit-Reset header fields.
    source_title: RFC 9333 RateLimit Fields
    source_url: https://datatracker.ietf.org/doc/html/rfc9333
    confidence: medium
  - id: fact-cs-api-http-ratelimit-fields-and-structured-fields-2
    statement: >-
      RFC 8941 defines structured field values for HTTP.
    source_title: RFC 8941 Structured Field Values
    source_url: https://datatracker.ietf.org/doc/html/rfc8941
    confidence: medium
  - id: fact-cs-api-http-ratelimit-fields-and-structured-fields-3
    statement: >-
      RFC 9110 defines Retry-After as information about the amount of time a
      client should wait before making another request.
    source_title: RFC 9110 HTTP Semantics
    source_url: https://datatracker.ietf.org/doc/html/rfc9110
    confidence: medium
completeness: 0.84
known_gaps:
  - Rate-limit interpretation depends on server policy, shared quota buckets, authenticated identity, burst limits, clock skew, distributed gateways, and whether Retry-After or RateLimit fields are authoritative for that API.
  - Header fields describe request pacing; they do not prove that a retried operation is idempotent or safe.
disputed_statements: []
primary_sources:
  - title: RFC 9333 RateLimit Fields
    type: rfc
    year: 2023
    url: https://datatracker.ietf.org/doc/html/rfc9333
    institution: IETF
  - title: RFC 8941 Structured Field Values
    type: rfc
    year: 2021
    url: https://datatracker.ietf.org/doc/html/rfc8941
    institution: IETF
  - title: RFC 9110 HTTP Semantics
    type: rfc
    year: 2022
    url: https://datatracker.ietf.org/doc/html/rfc9110
    institution: IETF
secondary_sources: []
updated: '2026-06-09'
ai_models:
  - gpt-5-codex
---

## TL;DR

HTTP RateLimit fields give API agents machine-readable quota evidence instead of forcing them to infer retry timing from generic 429 errors.

## Core Explanation

Agents that call APIs need to know when to pause, retry, batch, page, or ask for a higher quota. The useful evidence is the response status, RateLimit fields, Retry-After value, authentication identity, endpoint, method, request cost, and whether the operation is safe to replay.

Rate-limit fields should be treated as execution constraints, not merely diagnostics. Agents should preserve header values in logs, avoid retry storms, and combine quota evidence with idempotency and backoff policy.

## Source-Mapped Facts

- RFC 9333 defines the HTTP RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset header fields. ([source](https://datatracker.ietf.org/doc/html/rfc9333))
- RFC 8941 defines structured field values for HTTP. ([source](https://datatracker.ietf.org/doc/html/rfc8941))
- RFC 9110 defines Retry-After as information about the amount of time a client should wait before making another request. ([source](https://datatracker.ietf.org/doc/html/rfc9110))

## Further Reading

- [RFC 9333 RateLimit Fields](https://datatracker.ietf.org/doc/html/rfc9333)
- [RFC 8941 Structured Field Values](https://datatracker.ietf.org/doc/html/rfc8941)
- [RFC 9110 HTTP Semantics](https://datatracker.ietf.org/doc/html/rfc9110)