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: Health Gorilla providerId: health-gorilla created: '2026-06-21' modified: '2026-08-14' generated: '2026-08-14' method: searched source: https://developer.healthgorilla.com/reference/subscribing-to-events reconciled: false tags: - Health - Interoperability - FHIR - Clinical Data - Lab Ordering - Rate Limiting - Quotas - Throttling description: >- Health Gorilla publishes no request-rate ceiling and no rate-limit response headers. The full reference documentation was searched — the HTTP Status Codes page enumerates 400, 401, 403, 404, 409, 422, 500 and 503 and does not list 429 at all, and no X-RateLimit-*, RateLimit-* or Retry-After header appears anywhere in the reference. What Health Gorilla does publish are three concrete operational limits: a cap on active event subscriptions, a webhook delivery retry schedule with an auto-disable rule, and pagination defaults. Those are recorded below with their real values. Per-client request throttling, if any, is governed by the onboarding agreement and is not documented publicly. notes: >- The rate-limit gap is a real finding, not a harvesting failure. An agent calling this API has no runtime signal telling it when to slow down: no documented 429, no limit headers, no Retry-After. Backoff must be driven by 5xx responses and timeouts alone. Confirm any per-client throttling thresholds with Health Gorilla during onboarding. sources: - https://developer.healthgorilla.com/reference/http-status-codes - https://developer.healthgorilla.com/reference/subscribing-to-events - https://developer.healthgorilla.com/reference/handling-failures-retries - https://developer.healthgorilla.com/reference/pagination - https://developer.healthgorilla.com/reference/async-job-handling responseCodes: throttled: null throttled_note: >- No 429 Too Many Requests is documented. Previously recorded as 429; corrected on 2026-08-14 after reading the provider's published status-code table, which does not include it. responseHeaders: rate_limit_headers: none documented retry_after: not documented request_id_headers: [X-HG-Request-Id, X-Request-Id, X-Correlation-Id] note: >- The only per-request runtime headers Health Gorilla documents are the correlation trio, which support tracing and support escalation rather than throttling. limits: - name: Active Subscriptions scope: client metric: subscriptions limit: 30 window: concurrent documented: true increase: available on request exhaustion_status: 422 notes: >- Health Gorilla allows 30 active FHIR Subscriptions by default. Requests that exceed the cap return 422 Unprocessable Entity. source: https://developer.healthgorilla.com/reference/subscribing-to-events - name: Webhook Delivery Retries scope: subscription metric: delivery attempts limit: 4 window: per event documented: true schedule: ['~5 seconds', '~30 seconds', '~2 minutes', '~10 minutes'] notes: >- Exponential backoff across four attempts. After the final attempt the event is discarded and is never redelivered. source: https://developer.healthgorilla.com/reference/handling-failures-retries - name: Subscription Auto-Disable scope: subscription metric: consecutive failures limit: 10 window: 3 days secondary_limit: 20 documented: true notes: >- A subscription is disabled when the last successful delivery is 3 days or older and delivery has failed more than 10 times, or when no successful delivery has ever occurred and delivery has failed more than 20 times. Once disabled it must be re-enabled before notifications resume. source: https://developer.healthgorilla.com/reference/subscribing-to-events - name: Subscription Redelivery Interval scope: subscription metric: interval limit: 15 minutes documented: true notes: Failed notifications are retried at 15-minute intervals until delivery succeeds or the subscription is disabled. source: https://developer.healthgorilla.com/reference/subscribing-to-events - name: Search Page Size scope: request metric: results per page limit: not fixed parameter: _count documented: true notes: >- Default page size varies by resource type. Health Gorilla names _count=1000 as an example of an excessive page size to avoid. The ADT subscription search documents a _count default of 100. source: https://developer.healthgorilla.com/reference/pagination - name: API Requests scope: client metric: requests limit: not published documented: false notes: >- No per-second, per-minute or per-day request ceiling is published. Any per-client throttling is governed by the onboarding agreement. - name: Idempotency Key Retention scope: request metric: replay window limit: typically up to 1 hour documented: true notes: >- Not a rate limit, but the window that governs safe retry. A replayed POST with the same HG-Idempotency-Key and payload inside this window returns the original response. source: https://developer.healthgorilla.com/reference/idempotent-requests policies: - name: Asynchronous Retrieval description: >- Long-running federated queries such as $p360-retrieve return 202 Accepted and are polled for completed, partial or failed status rather than held open on a synchronous connection. This is the mechanism that keeps large record retrievals off the synchronous request path. source: https://developer.healthgorilla.com/reference/async-job-handling - name: Cursor Pagination description: >- Search and $everything responses page via an opaque server-generated _cursor carried on Bundle.link.next. Offset paging is discouraged for large datasets. source: https://developer.healthgorilla.com/reference/pagination - name: Client Backoff description: >- With no documented 429 or Retry-After, clients should apply exponential backoff with jitter on 500 and 503 responses and on timeouts. Health Gorilla documents 503 as "temporarily unavailable" and 500 as "try again later". source: https://developer.healthgorilla.com/reference/http-status-codes limit_count: 7 documented_limit_count: 6 related: - conventions/health-gorilla-conventions.yml - asyncapi/health-gorilla-webhooks.yml - errors/health-gorilla-problem-types.yml maintainers: - FN: Kin Lane email: kin@apievangelist.com x-evidence: - {url: 'https://developer.healthgorilla.com/reference/subscribing-to-events.md', http_status: 200, fetched: '2026-08-14'} - {url: 'https://developer.healthgorilla.com/reference/handling-failures-retries.md', http_status: 200, fetched: '2026-08-14'} - {url: 'https://developer.healthgorilla.com/reference/http-status-codes.md', http_status: 200, fetched: '2026-08-14'} - {url: 'https://developer.healthgorilla.com/reference/pagination.md', http_status: 200, fetched: '2026-08-14'}