specification: API Commons Rate Limits
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/RateLimits
provider: Bonneville Power Administration
providerId: bonneville-power-administration
generated: '2026-09-06'
method: probed
source: >-
  response headers observed on a live anonymous request to
  https://services3.arcgis.com/Iz3chmSt4P7oOoZy/arcgis/rest/services/BPA_ServiceArea/FeatureServer/0/query
created: '2026-05-04'
modified: '2026-09-06'
tags:
  - Energy
  - Federal Government
  - GIS
  - Rate Limiting
  - Throttling
description: >-
  BPA publishes no rate-limit documentation. The limits that do exist are enforced by the
  Esri platform hosting BPA's layers and are signalled on the wire in Esri request units,
  not requests — a model the X-RateLimit-* family cannot express. Everything below was read
  off a live response on 2026-09-06; nothing is quoted from documentation, because there
  is none.
documented_by_provider: false
limit_count: 1
headers:
  limit: x-esri-org-request-units-per-min
  remaining: null
  reset: null
  retryAfter: null
  cost: x-esri-query-request-units
  note: >-
    There is no X-RateLimit-Limit / -Remaining / -Reset family and no RateLimit-* (RFC 9239
    draft) family on this surface. `x-esri-org-request-units-per-min` carries BOTH the usage
    and the ceiling in one value, formatted `usage=<n>;max=<n>`. A client must parse that
    string; there is no separate remaining header to read.
limits:
- id: esri-org-request-units-per-minute
  scope: per-organization
  applies_to: the whole BPA ArcGIS Online tenant (org Iz3chmSt4P7oOoZy), shared across every caller
  window: 1 minute
  limit: 28800
  unit: request units
  burst: unknown
  observed_usage: 13
  cost_model: >-
    Each query consumes a variable number of units reported in x-esri-query-request-units;
    a simple bounded query observed 3 units. Cost scales with vertex count and result size,
    so a large geometry query costs more than a count-only query.
  evidence:
    url: https://services3.arcgis.com/Iz3chmSt4P7oOoZy/arcgis/rest/services/BPA_ServiceArea/FeatureServer/0/query?where=1%3D1&outFields=*&f=json
    http_status: 200
    fetched: '2026-09-06'
    headers_observed:
      x-esri-org-request-units-per-min: usage=13;max=28800
      x-esri-query-request-units: '3'
      x-esri-query-max-vertex-count: '8974'
  caveat: >-
    THIS IS A SHARED TENANT BUDGET, NOT A PER-CALLER ALLOWANCE. An integrator cannot reason
    about their own headroom from it, because the number moves with everyone else's traffic
    against BPA's org — including BPA's own maps and dashboards.
exhaustion_behavior:
  status_code: unknown
  body: unknown
  retry_after: unknown
  note: >-
    Not induced and not published. Deliberately not guessed — an invented 429 contract is
    worse than an acknowledged gap.
transfer_limits:
- scope: per-response
  layers_1000:
  - BPA_ServiceArea
  - BPA_CustomerPublics
  - BPA_CustomerIOU
  - BPA_CustomerTribal
  - BPA_TransmissionLines_View
  - BPA_RightofWay_View
  - ColumbiaRiverBasin
  layers_2000:
  - BPA_TransmissionStructure_View
  signal: exceededTransferLimit
  note: >-
    A per-response feature cap, distinct from rate limiting. When exceeded the response sets
    exceededTransferLimit true and the client pages with resultOffset / resultRecordCount.
  evidence: layer definitions fetched at .../FeatureServer/0?f=json, 2026-09-06
polite_use:
  cache_control: public, max-age=30, s-maxage=30
  etag: true
  guidance: >-
    Responses are cacheable for 30 seconds and carry an ETag. Use conditional GET and do not
    poll a GIS layer faster than its cache window. The transmission.bpa.gov operational text
    feeds refresh every 5 minutes; polling them faster returns identical bytes.
other_surfaces:
- surface: transmission.bpa.gov operational data files
  documented_limits: none
  headers: none
  note: Static file serving on IIS. No rate-limit headers observed and no published policy.
notes:
- >-
  This file previously declared an X-RateLimit-Limit / -Remaining / -Reset header family and
  scaffold per-tier quotas, written by the 2026-05-04 bulk sweep. None of those headers is
  returned by any BPA endpoint. Replaced 2026-09-06 with the headers actually on the wire.