API concepts
Error handling
The API returns standard error objects:
{
"status_code": "number",
"message": "string",
"error_detail": "string | null",
"failedReason": "string | null"
}
See the reference for particular endpoints to see exactly what errors are possible.
Status codes
The API uses normal HTTP status codes to describe the response.
For example, a good response will come back with a 2xx code, and bad requests will get 4xx.
This means that generally speaking, code like if (res.ok) ... is enough to understand if a request has succeeded.
Data format
The API supports JSON.
Some endpoints accept image data or other files. When calling them, add a Content-Type: multipart/form-data header.
Check the reference for the particular endpoint if unsure.
Rate limits
We limit how quickly you can make requests to keep the API fast and reliable for everyone. Most integrations will never hit these limits. If you do, the API tells you exactly how long to wait.
Limits
Request rate. Each API token can make up to 300 requests per minute. This applies across all endpoints.
Free trial limits. Trial teams also have:
- a lower per-minute limit on checks
- a cap on the total number of risk checks they can run
Upgrading removes the trial limits.
When you hit a limit
The API responds with a 429 Too Many Requests and an error_code explaining which limit you hit:
{
"status_code": 429,
"message": "You've hit a rate limit. Try again shortly.",
"error_code": "RATE_LIMITED",
"retry_after_seconds": 12
}
error_code | What it means | What to do |
|---|---|---|
RATE_LIMITED | You're sending requests too quickly | Wait for retry_after_seconds, then retry |
QUOTA_EXHAUSTED | Your trial has used all its risk checks | Upgrade to continue. Retrying won't help. |
The Retry-After header contains the same value as retry_after_seconds. Refused requests don't count towards your limit, so retrying after the wait won't extend it.
Handling limits gracefully
- Respect
Retry-After. Wait at least that long before retrying. Retrying sooner will be refused again. - Retry with backoff. If you're retrying automatically, add a small random delay (jitter) so many requests don't retry at the same moment.
- Don't retry
QUOTA_EXHAUSTED. It won't succeed until the team is upgraded. - Spread out bulk work. If you're processing a large batch, pace your requests rather than sending them all at once.
Need a higher limit?
If your integration needs more than 300 requests per minute, contact us and tell us about your use case.