API Rate Limits

To ensure system stability and fair usage, Planbok implements rate limiting across all API endpoints. These limits are designed to accommodate standard integration needs while protecting the infrastructure from bursts or abuse.

Default Rate Limits

Rate limits are primarily based on the organization identifier or the client's IP address, depending on the authentication context.

[!NOTE] Signing operations have a higher threshold to support high-velocity automated payouts and institutional treasury movements.

Authentication Limits

Special limits apply to sensitive authentication and security-related endpoints:

• IP-based Limits: 5 requests per 5 minutes.
• Email-based Limits: 5 requests per hour (e.g., for login or recovery link sends).

Error Response

When a rate limit is exceeded, the API will return an HTTP 429 Too Many Requests status code with the following JSON response:

Code
{
  "status": 429,
  "message": "Too many requests, please try again later"
}

Best Practices

To avoid hitting rate limits, we recommend the following strategies:

1. Polling intervals: Instead of aggressive polling, use our Webhooks to receive real-time notifications for transaction and wallet state changes.
2. Backoff strategy: Implement an exponential backoff strategy when you encounter a 429 error.
3. Idempotency: Use the idempotencyKey for all POST requests. This ensures that even if you retry a rate-limited or timed-out request, the operation will only be executed once.
4. Metadata Cache: Use the Supported Blockchains endpoint sparingly by caching the results, as these parameters change infrequently.

[!TIP] Planbok does not currently send custom X-RateLimit headers. Applications should rely on the 429 status code as the trigger for backoff logic.