Errors and rate limits

Status codes, error codes and the limits on how often you can call the API.

Status codes

Field	Type	Description
200 / 201	success	It worked (201: created)
204	success	It worked; nothing to return
400	error	Something in the request is wrong
401	error	Missing, invalid or expired key or token (see WWW-Authenticate)
403	error	Missing permission, address not in the IP allowlist, key blocked, or your plan doesn't include the API
404	error	Not found (also anything that isn't yours)
409	error	Duplicate (e.g. same invitation twice)
413	error	The request body is too large
415	error	Wrong Content-Type (send application/json)
429	error	Too many requests
500	error	Our problem; safe to retry

Error codes

Field	Type	Description
invalid_key	401	The key is missing, wrong or revoked
invalid_token	401	The access token is missing, wrong or revoked
key_expired	401	The key has expired: create or rotate a key
token_expired	401	The access token has expired: request a new one
key_blocked	403	Our team blocked the key; the owner was emailed why
ip_not_allowed	403	The request came from an address outside the key's IP allowlist
https_required	403	The request came over plain HTTP
plan_required	403	The company's plan doesn't include the API
insufficient_scope	403	The key doesn't have the permission this request needs
invalid_request	400	A field is missing or wrong (see fields)
credentials_in_url	400	A key or token was sent in the address or body; only the Authorization header is accepted
business_required	400	Your key can use more than one business: name one
not_found	404	No such thing, or not yours
duplicate_invitation	409	This customer was invited in the last 30 days, or this order already has an invitation
unsubscribed	409	The customer unsubscribed from your invitations
idempotency_conflict	409	The Idempotency-Key was used with a different request
payload_too_large	413	The body is over 64 KB
unsupported_media_type	415	The body isn't Content-Type: application/json
rate_limited	429	Over the per-second limit; see Retry-After
too_many_auth_failures	429	Too many failed authentications from this address; wait a minute
monthly_limit_reached	429	Over the monthly limit until the next month
internal_error	500	Something went wrong on our side

Rate limits

10 requests per second per key, and a monthly total per company (Pro 100,000, Enterprise 1,000,000 or custom). Every response includes these headers.

Field	Type	Description
RateLimit-Limit	header	Requests allowed per second for this key
RateLimit-Remaining	header	Requests left in this second
RateLimit-Reset	header	Seconds until the limit resets
RateLimit-Monthly-Limit	header	Requests allowed this month
RateLimit-Monthly-Remaining	header	Requests left this month
Retry-After	header	On 429: seconds to wait
Request-Id	header	Quote it when you contact support
WWW-Authenticate	header	On 401 and insufficient_scope: what went wrong (RFC 6750)

HTTP/1.1 429 Too Many Requests
Retry-After: 1
RateLimit-Limit: 10
RateLimit-Remaining: 0
RateLimit-Reset: 1

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again in 1 second.",
    "request_id": "req_4Hq1x2"
  }
}

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "Something in the request is wrong.",
    "request_id": "req_9Tz0k1",
    "fields": [
      "email"
    ]
  }
}