Errors
GuidesUpdated June 14, 2026
Errors
API errors return a JSON body with error (code), message (human-readable), and request_id (a unique id for the request, useful for support). Some responses include an optional detail field.
Every authenticated response (success or error) also carries the X-Request-Id header. Include the request_id when contacting support. (The unauthenticated GET /api/v1/health check is the one exception and does not return X-Request-Id.)
HTTP status codes
| Status | Meaning |
|---|---|
| 200 | Success. |
| 201 | Created (e.g. create campaign shell, branch, create signature). |
| 202 | Accepted (async job accepted; e.g. generate-batch). |
| 400 | Bad Request – invalid body, missing or invalid fields. |
| 401 | Unauthorized – missing or invalid API key. |
| 402 | Payment Required – insufficient credits. |
| 403 | Forbidden – missing required scope, resource not in this workspace, or a plan limit (e.g. campaign build limit) was reached. |
| 404 | Not Found – resource not found or not in this workspace. |
| 409 | Conflict – NOT_READY (e.g. list not yet completed) or CONFLICT (e.g. an Idempotency-Key reused with a different body, or an in-flight duplicate). |
| 422 | Unprocessable – UNPROCESSABLE (semantically invalid request the server understood but can't process). |
| 429 | Too Many Requests – per-key rate limit (RATE_LIMITED, honor Retry-After) or workspace quota limit (WORKSPACE_LIMIT). |
| 500 | Internal Server Error – server-side failure. |
Error body format
{
"error": "ERROR_CODE",
"message": "Human-readable description.",
"request_id": "9f1c0b3a-..."
}Optional: "detail" — additional technical context (a string or an object, depending on the error).
Common error codes
| Code | HTTP | Description |
|---|---|---|
| UNAUTHORIZED | 401 | Missing or invalid API key. Send Authorization: Bearer <key> or X-API-Key: <key>. |
| BAD_REQUEST | 400 | Invalid JSON, missing required field (e.g. lead, leads), or invalid value (e.g. lead missing email). |
| INSUFFICIENT_CREDITS | 402 | Not enough credits for this workspace. Upgrade or wait for reset. |
| FORBIDDEN | 403 | The API key is missing a required scope, the resource is not in the workspace tied to your API key, or a plan limit was reached (e.g. campaign build limit — detail.reason: "campaign_build_limit"). |
| NOT_FOUND | 404 | Campaign or list not found, or not in this workspace. |
| NOT_READY | 409 | A resource is not in a state that allows this action yet (e.g. export called before the list completed, or VP generation before SP/LM/RR selections). |
| CONFLICT | 409 | An Idempotency-Key was reused with a different request body, or a request with the same key is still in flight. |
| UNPROCESSABLE | 422 | The request was understood but is semantically invalid (e.g. branching from a step with no active configuration). |
| RATE_LIMITED | 429 | Per-key rate limit exceeded. Honor the Retry-After header. See Rate Limits. |
| WORKSPACE_LIMIT | 429 | A workspace quota was hit — too many concurrent batch jobs, or a storage / lifetime-upload limit (document imports). Retry later or free up quota. |
| INTERNAL_ERROR | 500 | Server error. Retry with backoff; contact support if it persists. |
Example error response
{
"error": "INSUFFICIENT_CREDITS",
"message": "You have 0 credits remaining. Please upgrade your plan.",
"request_id": "9f1c0b3a-..."
}Client guidance
- 401: Check that the API key is correct and sent in
Authorization: Bearer <key>orX-API-Key. - 402: Check usage/credits in the MachFive app; upgrade or wait for quota reset.
- 404: Verify the campaign or list ID and that it belongs to the workspace of the API key.
- 500: Retry with exponential backoff; if repeated, contact support with request ID or timestamp if available.