Errors and rate limits
Status codes, error codes and the limits on how often you can call the API.
In short
When a request fails, the API answers with an HTTP status code and a short error code that says what to fix. Requests are also limited per second and per month, and every response carries headers that show how much of the limit is left. Check the authentication page if you get 401 or 403.
- 4xx status codes mean the request needs fixing; 5xx mean try again later.
- Each error has a code, such as key_expired or ip_not_allowed, and a message.
- 429 means a rate limit was reached: wait for the time in the Retry-After header.
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"
]
}
}