Platform Limits
Default Rate Limits
The Basis Theory API has rate limits applied to ensure the speed and consistency of our systems. Rate Limits will always apply to the lowest Rate available for a given request. For example, a request to POST /tokens with a private API key is limited to 200 Requests / 10 Seconds by the resource limit, even though the private application limit is higher. Test and production tenants have the same default rate limits.
API Resource Rate Limits
| Resource | Counter | Rate | Action |
|---|---|---|---|
| GET /tokens, POST /tokens/search, OR POST /detokenize | API Key AND IP | 100 req / 10 s | Throttle |
| POST /tokens OR /tokenize | API Key AND IP | 200 req / 10 s | Throttle |
| PATCH /tokens/{id} | API Key AND IP | 200 req / 10 s | Throttle |
| DELETE /tokens/{id} | API Key AND IP | 200 req / 10 s | Throttle |
| POST /network-tokens | API Key AND IP | 200 req / 10 s | Throttle |
| POST /network-tokens/{id}/cryptogram | API Key AND IP | 200 req / 10 s | Throttle |
| PUT /network-tokens/{id}/suspend, PUT /network-tokens/{id}/resume, OR DELETE /network-tokens/{id} | API Key AND IP | 200 req / 10 s | Throttle |
| ANY /account-updater/* | API Key AND IP | 25 req / 10 s | Throttle |
| ANY /documents* | API Key | 25 req / 1 min | Throttle |
Application Type Rate Limits
Private Application
| Resource | Counter | Rate | Action |
|---|---|---|---|
| ANY | API Key OR IP | 2000 req / 10 s | Throttle |
Public Application / Session Key
| Resource | Counter | Rate | Action |
|---|---|---|---|
| ANY | IP and API Key | 100 req / 60 s | 60s Block |
Management Application
| Resource | Counter | Rate | Action |
|---|---|---|---|
| ANY | API Key | 200 req / 1 min | 60s Block |
Proxies
Unauthenticated / Whitelabel Proxies
| Resource | Counter | Rate | Action |
|---|---|---|---|
| ANY | Proxy Key AND IP | 50 req / 10 s | Throttle |
| ANY | Custom Hostname AND IP | 50 req / 10 s | Throttle |
Additional Limits for Proxy Requests
| Limit Type | Value | Behavior |
|---|---|---|
| Ephemeral Proxy Destination Response Timeout | 25 seconds | Returns HTTP 408 if the destination exceeds the timeout. See Destination URLs. |
| Pre-configured Proxy Destination Response Timeout | 25-second default; 55-second maximum | Returns HTTP 408 if the destination exceeds the configured timeout. If your integration needs a longer timeout, contact Basis Theory to discuss your requirements. For operations that need longer than 55 seconds, consider asynchronous Reactors. See Destination URLs. |
IPs
IP-Based Global Rate Limit
| Resource | Counter | Rate | Action |
|---|---|---|---|
| ANY | IP | 2000 req / 10 s | 30s Block |
Legacy Rate Limits
Legacy API Keys
This applies to API keys that don't contain _prod_, _test_, _pub_ or _session_. In the Portal, these keys have a Legacy badge on the Application. This limit applies to every tenant, whether test or production, and legacy keys aren't eligible for rate limit increases. To get the limits listed above, create a new API key for the Application.
| Method | Resource | Counter | Rate | Action |
|---|---|---|---|---|
| ANY | ANY | API Key | 100 req / 60 s | Throttle |
Error Codes
| Status Code | Meaning |
|---|---|
429 | Request has been rate limited |
Other Limits
Default Quotas
Quotas are Tenant specific limits that can be adjusted by Basis Theory. Below are some of the default Quota's applied to all tenants as they are created - to find the full list of Quota' or to request a change, please visit your tenant's Quota page.
| Quota Name | Limit |
|---|---|
| Rate Limit | Default |
| Log Retention | 24 hours |
| Tokenize Limit | 5 tokens |
| Detokenize Limit | 5 tokens |
| CVC Retention | 1 hour |
| Token Intent Retention | 24 hours |
| Applications Limit | 30 applications |
A successful POST /applications response includes a remaining_applications field with the number of applications the tenant can still create. Once the limit is reached, the request fails with a 400 and the Application.Error.ApplicationLimitReached title.
Code Execution
Applicable to Reactors and Proxy Transforms.
| Metric | Limit | Note |
|---|---|---|
| Maximum code length | 50K characters | Please reach out if your use case requires more characters. |
| Payload Size | 1 MB | Please reach out if your use case requires larger payloads. |
| Warm concurrency | 0 | A request cold starts only when no idle warm instance is available. Each instance handles one request at a time, so a burst above the instances already warm cold starts additional instances. See Warm Concurrency for when to request configured warm instances. |
| Synchronous Timeout | 30 seconds | Synchronous Reactor Invoke and Pre-configured Proxy Invoke code executions have a maximum timeout of 30 seconds. Node.js runtime images can be configured from 10 to 30 seconds. |
Asynchronous node-bt Timeout | 300 seconds | Legacy node-bt asynchronous Reactor invocations time out after 300 seconds. |
| Asynchronous Node.js Runtime Timeout | 900 seconds | Asynchronous Reactors using a Node.js runtime image can configure runtime.timeout from 10 to 900 seconds. |
Account Updater
The maximum supported Batch Account Updater request file size is 30 MB per file (approx. 300k tokens).
If you need to update more than 300k tokens at a time, you can split your request into multiple files and create multiple jobs in parallel.
Network Tokens
Operations that reach the card networks are each limited to 200 requests / 10 seconds (20 TPS) per Tenant by default. This applies to provisioning a Network Token (POST /network-tokens), generating a cryptogram (POST /network-tokens/{id}/cryptogram), and suspending (PUT /network-tokens/{id}/suspend), resuming (PUT /network-tokens/{id}/resume), or deleting (DELETE /network-tokens/{id}) a Network Token. This limit is set to stay within the throughput the card networks support for network token operations, and it comfortably covers normal one-time (CIT) and recurring (MIT) payment flows.
Reads do not reach the card networks and are not subject to the Network Token-specific limit. Retrieving a Network Token (GET /network-tokens/{id}) falls under the Private Application default of 2000 requests / 10 seconds. This gives batch jobs that read Network Token details (for example, to check expiration before reprovisioning) significantly more headroom than the 20 TPS limit on network operations.
When a request is throttled, the API returns a 429. If you receive one, slow your request rate and retry — for example, queue requests and replay them at a reduced rate rather than retrying immediately.
If you expect sustained volume above 20 TPS, or you are planning a higher-volume migration or wallet backfill, contact us ahead of time. We can coordinate a temporary throughput increase with the card networks for the duration of your migration. These increases are arranged in advance and granted for a limited window, so reach out before you begin.