Skip to main content

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_codeWhat it meansWhat to do
RATE_LIMITEDYou're sending requests too quicklyWait for retry_after_seconds, then retry
QUOTA_EXHAUSTEDYour trial has used all its risk checksUpgrade 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.