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: Avalara
providerId: avalara
created: '2026-05-04'
# Provenance stamped 2026-08-11: this artifact was written by the API Evangelist
# bulk sweep dated 2026-05-04, not harvested from the provider. See roadmap#35.
method: generated
modified: '2026-05-05'
reconciled: false
notes: Avalara documents general best-practice retry behavior but does not publish numeric per-second
  rate limits on its public developer portal. Limits scale with the customer's AvaTax subscription
  tier and are enforced server-side.
tags:
  - Tax Compliance
  - Sales Tax
  - VAT
  - Rate Limiting
description: Rate limit posture for the Avalara AvaTax REST API and supporting services (Returns,
  CertCapture, E-Invoicing). Avalara enforces per-account throttles tied to subscription tier; the
  platform returns standard 429 / 503 codes and clients are expected to back off and retry. Numeric
  thresholds are not posted publicly.
sources:
  - https://developer.avalara.com/
  - https://developer.avalara.com/avatax/dev-guide/best-practices-for-error-handling/
responseCodes:
  throttled: 429
  serviceUnavailable: 503
  serverError: 500
limits:
  - name: AvaTax REST API
    scope: account
    metric: varies
    limit: see Avalara support / subscription tier
    notes: Numeric per-second limits are not publicly posted; thresholds depend on the customer's
      AvaTax subscription size.
  - name: Sandbox
    scope: sandbox-account
    metric: varies
    limit: lower than production
    notes: Sandbox is intended for integration development; sustained load testing should be coordinated
      with Avalara support.
policies:
  - name: Backoff Strategy
    description: Avalara's developer guide recommends exponential backoff with jitter on 429 / 503 / 5xx
      responses; honor Retry-After when present.
  - name: Idempotency
    description: Use the documented transaction code (CompanyCode + DocCode) so retried CreateTransaction
      calls return the existing transaction rather than creating duplicates.
  - name: Batch Where Possible
    description: For high-volume reconciliation, prefer the Batch APIs over single-call CreateTransaction
      to minimize calls per transaction.
  - name: Avoid Sandbox for Load Testing
    description: Sandbox carries lower thresholds than production; coordinate any load test with Avalara
      support to use a sized environment.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com