Skip to content
All documentation chapters
On this page

Supra Core API — Public Client Documentation

Chapter 04 — Rate Limits

1. Purpose

Rate limits protect API availability by bounding request volume. Limits depend on the enabled plan associated with the client's API key. This chapter describes observable client behavior without documenting private enforcement details.

2. Rate-Limit Response

When a request exceeds an applicable allowance, the API can return:

  • HTTP 429;
  • ok=false;
  • public error code RATE_LIMITED;
  • a public error message.

Illustrative response:

{
  "ok": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded."
  }
}

429 is not an authentication failure. Do not replace a valid key merely because a request was rate-limited.

3. Client Response to 429

On 429:

  1. stop immediate retry;
  2. reduce request frequency and concurrency;
  3. wait using exponential or bounded backoff;
  4. add jitter before retrying;
  5. reuse cached data when appropriate;
  6. preserve a sanitized diagnostic record.

Retry-After may be absent unless explicitly documented. If present and valid, clients should respect it. If absent, use a conservative local backoff policy.

An illustrative sequence is:

1 second
2 seconds
4 seconds
8 seconds
16 seconds

Add a small random jitter and cap the maximum delay. Do not retry forever.

Reset or reduce the delay only after requests succeed consistently.

5. Preventing Rate Limits

5.1 Cache common reads

Cache shared market snapshots, pair lookups, health results, and historical candle pages for an appropriate bounded period.

5.2 Poll responsibly

Do not run tight request loops. Poll according to the data's update needs rather than UI render frequency.

5.3 Coordinate workers

Multiple processes using the same client access should share a request budget instead of acting independently.

5.4 Paginate incrementally

Use limit and offset, stop on an empty or shorter-than-limit page, and avoid repeatedly fetching complete history.

5.5 Avoid synchronized bursts

Stagger scheduled jobs and add jitter so several workers do not request the same endpoint simultaneously.

6. Concurrency

High concurrency can consume an allowance quickly even when each worker sends requests slowly.

Client-owned backends should:

  • cap concurrent upstream requests;
  • collapse identical in-flight requests;
  • cache common responses;
  • queue non-urgent analytics work;
  • avoid one upstream request per frontend component.

7. Plan and Limit Information

Use the access guidance supplied by TCP Labs to understand the limits assigned to the enabled plan. Available plans, rate limits, permitted usage, and commercial terms are provided separately. This documentation does not promise a free tier or specific commercial terms. Do not infer limits from:

  • another client;
  • a short successful test;
  • a missing Retry-After header;
  • the endpoint's limit parameter.

The pagination limit controls rows per response. It is not the same as a request-rate allowance.

When rate limiting applies, the API key uses the active minute and daily allowances assigned to its plan. Scope labels and burst_limit, when communicated, are informational and do not imply route-specific enforcement or an additional burst counter unless a later public contract explicitly states otherwise.

8. Retry Decision Guide

Status Retry? Recommended action
200 No retry needed Process the response, including valid empty data
400 No, until corrected Fix parameters
401 No automatic loop Fix authentication
404 Usually no Verify route
405 No Use the documented method
429 Yes, later Back off, add jitter, reduce load
500 Bounded retry Retry a small number of times with backoff

9. Scope and Data Exposure

Clients can rely on the documented 429 response and the limits assigned to their enabled plan. Internal quota counters and capacity are not part of the response contract.

10. Chapter Summary

Treat 429 as a signal to reduce request load. Cache common reads, coordinate workers, paginate incrementally, use bounded backoff with jitter, and follow the request guidance supplied for your client.