Errors and rate limits
The API uses standard HTTP status codes. Every error response has the same JSON shape.
Error format
json
| Field | Description |
|---|---|
name | Error type, for example BadRequest, NotFound. |
message | Human-readable explanation. |
code | HTTP status code. |
className | Kebab-case version of name. |
data | Optional details: validation errors, rate-limit counters, conflicting records. |
Status codes
| Status | Name | Meaning |
|---|---|---|
200 | OK | Success. |
201 | Created | Record created (POST). |
400 | BadRequest | Invalid body or query string (unknown parameter, wrong type, missing required field). Check data. |
401 | NotAuthenticated | Invalid or inactive API key. |
403 | Forbidden | No API key sent, or the key cannot perform this action on this resource. |
404 | NotFound | The record does not exist, was deleted, or belongs to another organization. |
409 | Conflict | The change conflicts with existing data. |
429 | TooManyRequests | Rate limit exceeded. |
500 | GeneralError | Unexpected server error. Retry later; contact support if it persists. |
Rate limits
Requests made with an API key are counted per organization in fixed windows.
| Limit | Default |
|---|---|
| Requests per window | 1,000 |
| Window length | 3,600 seconds (1 hour) |
Your organization may have a different limit; contact support to raise it. When you go over the limit you get:
json
data.retryAfter is the number of seconds until the window resets. Wait that long before retrying.
Retrying safely
- Retry
429,500,502,503and network errors with exponential backoff. GET,PATCHandDELETEare safe to retry.POSTcreates a new record each time: before retrying aPOSTthat may have succeeded, list with a filter (for example byemail) to check it does not already exist.- Do not retry
400,401,403or404without changing the request.
Report an issue with this documentation
Please log in to report issues with our documentation.