Vision Developers

Rate limits

Rate controls are coordinated through PostgreSQL so limits remain consistent across application instances.

Policy layers

Token exchange applies global, source, and authenticated-client controls. Platform operations apply client, App, and scope-aware controls. Stored bucket keys are one-way digests rather than raw source or client values.

Limits protect the shared service and the target App independently. A successful token exchange does not reserve capacity on a resource server. Increasing concurrency can reduce useful throughput when a client is already limited.

Known token policy

The current Vision Core implementation evidence applies layered PostgreSQL-backed controls to token exchange, including a shared global bucket, a bounded source/client bucket before authentication, and a higher authenticated-client bucket. These values are preview implementation details rather than a stable service-level commitment; operation pages publish a numeric limit only when the approved contract declares one.

Rate-limit storage uses opaque one-way bucket keys so administrative evidence does not retain raw source/client text. If the shared limiter dependency is unavailable, token exchange fails closed rather than issuing without policy.

Response headers

A limited response returns 429, Retry-After, the current request ID, and bounded allowance metadata where appropriate. Vision Core may return x-ratelimit-limit and x-ratelimit-remaining. Treat header names case-insensitively and do not assume every App emits the same set.

Backoff

Wait for the supplied interval, then retry with jitter. Do not rotate client IDs, vary forwarded headers, or increase concurrency to evade a policy. Persistent 429 responses usually indicate a grant or workload design that needs review.

Use exponential backoff bounded by both attempts and elapsed time. For example: wait at least Retry-After; otherwise choose a random delay between zero and min(cap, base × 2^attempt). Stop when the request deadline or business freshness window expires.

Implementation example

  1. Set a total deadline and maximum attempt count before the first request.
  2. Give each attempt a shorter timeout than the total deadline.
  3. Return immediately for any status other than 429 and handle that status normally.
  4. On 429, parse Retry-After, choose at least that delay, and add bounded jitter.
  5. Stop and return the rate-limit error if the next delay crosses the total deadline.
  6. Otherwise wait and retry, preserving the same safe operation semantics.

Automatic retries are safest for idempotent reads. Before retrying a mutation, follow its idempotency and concurrency contract.

Capacity planning

  • Cache short-lived access tokens in server memory and share them within one process instead of exchanging per API call.
  • Request only the scopes needed for the workload.
  • Bound worker concurrency and queue depth.
  • Paginate sequentially unless the operation documents safe partitioning.
  • Use webhook/event delivery instead of aggressive polling where an approved event exists.
  • Record status, safe request ID, latency, attempt count, and remaining allowance—not credentials or private payloads.
  • Test expected peak and failure-recovery traffic in an approved environment before production.

Numeric resource-server quotas, burst size, refill algorithm, and account-level capacity are not yet stable public commitments. Do not size a production integration from the preview token implementation alone.