API Reference

Rate limits

Every API call is subject to a rate limit. Pineprompt returns the standard rate-limit headers on every response so that your client may self-throttle, and falls back to a 429 response once a client has exceeded its quota.

The limit

100 requests per second, keyed by API key. Unauthenticated requests are keyed by IP address instead.

The window is one second, so bursting 100 calls inside a single second and then waiting is perfectly acceptable. Sustained traffic above 100 requests per second will, however, begin to receive 429.

Response headers

Every response from the API carries the standard rate-limit headers so that your client may stay below the limit without polling:

Field	Type	Description
X-RateLimit-Limit	integer	The maximum number of requests allowed in the current window (100).
X-RateLimit-Remaining	integer	The number of requests remaining in the current window.
Retry-After	integer	The number of seconds to wait before issuing the next request. Only present on a `429` response.
X-RateLimit-Reset	integer	A Unix timestamp identifying when the current window resets. Only present on a `429` response.

The 429 response shape

{
  "message": "Too Many Attempts."
}

Recommended client behavior

On a 429 response, you should sleep for the number of seconds in Retry-After before retrying. Do not retry immediately.
For bulk operations, you may wish to pace your client at 90 requests per second or so, which leaves a small amount of headroom for retries.
If you operate from a fleet of workers, the workers should share a single token. The limit is enforced per token, so spreading traffic across machines does not raise your ceiling.
Of course, if you genuinely need a higher limit, please contact us.