Errors
ReferenceUpdated February 18, 2025
Errors
API errors return a JSON body with at least error (code) and message (human-readable). Some responses include an optional detail field.
HTTP status codes
| Status | Meaning |
|---|---|
| 200 | Success. |
| 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 – resource exists but is not in this workspace. |
| 404 | Not Found – resource not found or not in this workspace. |
| 409 | Conflict – e.g. list not yet completed (NOT_READY; poll list status first). |
| 429 | Too Many Requests – workspace concurrent job limit reached (generate-batch). Try again later. |
| 500 | Internal Server Error – server-side failure. |
Error body format
{
"error": "ERROR_CODE",
"message": "Human-readable description."
}Optional: "detail": "Additional technical detail".
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 | Campaign (or list) is not in the workspace tied to your API key. |
| NOT_FOUND | 404 | Campaign or list not found, or not in this workspace. |
| NOT_READY | 409 | List not yet completed (e.g. export called too early). Poll GET /lists/:id first. |
| WORKSPACE_LIMIT | 429 | Too many concurrent batch jobs in this workspace. Retry later. |
| 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."
}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.