Errors and limits
Status codes, error shapes, sign-in limits and how to retry.
#Error shape
Most errors are a JSON object with an error message. Sign-in endpoints use message instead.
Most endpoints
{ "error": "Lead name is required" }Sign-in endpoints
{ "message": "Invalid credentials" }#Status codes
| Status | When | What to do |
|---|---|---|
| 200 | The request worked | Read the response. |
| 201 | A record was created | The response is the new record. |
| 400 | Something is missing or invalid, for example no organisation header or no name | Fix the request. The message says what. |
| 401 | Token missing, invalid or expired, or two-factor not finished | Refresh your token or sign in again. |
| 403 | You are not allowed, or the plan limit is reached, or a view-only session tried to change data | Check your role and plan. |
| 404 | The record does not exist in your organisation | Check the id. |
| 429 | Too many sign-in attempts | Wait and try again. |
| 500 | Something went wrong on our side | Retry later and contact support if it continues. |
| 503 | The service is briefly unavailable | Retry after a short wait. |
#Common 401 messages
| Message | Meaning |
|---|---|
| Authentication token required | No Authorization header was sent. |
| Token invalid or expired | Refresh your token. |
| Two-factor verification required | You used a temporary token. Finish /login/verify-2fa. |
| Invalid or deactivated user | The account is inactive. |
#Sign-in limits
- Sign-in and one-time code requests: 20 attempts per 15 minutes from one network.
- Verification code attempts: 10 per 15 minutes.
Sign in once and reuse the token. Refresh it when it expires instead of signing in again for every call.
#Retry well
- Retry 503 and network errors with a short, growing wait.
- Do not retry 400, 401 or 403 without changing something.
- Never retry a POST blindly. If you did not see the response, check whether the record was created.