Errors and rate limits

The API uses standard HTTP status codes. Every error response has the same JSON shape.

Error format

json
FieldDescription
nameError type, for example BadRequest, NotFound.
messageHuman-readable explanation.
codeHTTP status code.
classNameKebab-case version of name.
dataOptional details: validation errors, rate-limit counters, conflicting records.

Status codes

StatusNameMeaning
200OKSuccess.
201CreatedRecord created (POST).
400BadRequestInvalid body or query string (unknown parameter, wrong type, missing required field). Check data.
401NotAuthenticatedInvalid or inactive API key.
403ForbiddenNo API key sent, or the key cannot perform this action on this resource.
404NotFoundThe record does not exist, was deleted, or belongs to another organization.
409ConflictThe change conflicts with existing data.
429TooManyRequestsRate limit exceeded.
500GeneralErrorUnexpected server error. Retry later; contact support if it persists.

Rate limits

Requests made with an API key are counted per organization in fixed windows.

LimitDefault
Requests per window1,000
Window length3,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, 503 and network errors with exponential backoff.
  • GET, PATCH and DELETE are safe to retry. POST creates a new record each time: before retrying a POST that may have succeeded, list with a filter (for example by email) to check it does not already exist.
  • Do not retry 400, 401, 403 or 404 without changing the request.

Report an issue with this documentation

Please log in to report issues with our documentation.