Errors
HTTP status codes and error payloads.
Most JSON errors use a simple shape:
{ "error": "Human-readable message" }Validation failures may add Zod details or campaign issues[] arrays.
Common status codes
| Status | When |
|---|---|
| 400 | Invalid query/body, business rule failure, structural campaign validation |
| 401 | Missing/invalid API key or Bearer token |
| 403 | Suspended account, no owner access to X-Workspace-Id, or insufficient session role (API keys always resolve as owner and are not blocked by workspace 2FA policy) |
| 404 | Resource not in workspace |
| 409 | Conflict (duplicate inbox email, duplicate inbox tag name) |
| 422 | Blocklisted email on lead create/import, inbox verify failure |
| 429 | Rate limit — see Rate limits |
| 500 | Unexpected server error |
Machine-readable codes
Some responses include a code field:
| Code | Meaning |
|---|---|
RATE_LIMIT_EXCEEDED | Per-key minute bucket exhausted |
WORKSPACE_TWO_FACTOR_REQUIRED | Workspace requires 2FA; session user has not enrolled (not returned for Bearer API key calls) |
Workspace context errors
- Missing `X-Workspace-Id` on API key requests → 400
- Key owner is not owner of the workspace → 403
Tips
- Log
X-RateLimit-Remainingto throttle client-side concurrency. - On 400 with
issues[], fix campaign/sequence structure before retrying activation or saves.