{
"status": 200,
"message": "Domains fetched successfully",
"data": {}
}success in place of status. The endpoint page shows the exact shape.{
"status": 404,
"message": "Workspace not found",
"errorId": "b3a1f0c2-6d47-4f1e-9a52-0c8e5d7a1b34"
}| Field | Description |
|---|---|
status | The HTTP status code, repeated in the body. |
message | A human-readable reason. Branch on the HTTP status, not on message text, because wording can change. |
errorId | A UUID for this occurrence. Quote it when you contact support@zapmail.ai. |
| Where | Shape |
|---|---|
| Rate limit exceeded (429 from the API gateway) | { "error": "Too many requests" }. See Rate Limits. |
| A few inline failures on money-moving endpoints (wallet, purchases) | { "message": "..." } without status or errorId. The endpoint page notes where. |
| A path that does not exist | A non-JSON 404 page, because no endpoint handled the request. |
errorId is endpoint-level and a 429 with only error is the API rate limit.message joins every failed rule with a comma and a space. There is no errors array.{
"status": 422,
"message": "domains must be a non-empty array, useWallet must be a boolean",
"errorId": "0f6c3a9e-7b21-4c85-8d14-3e92a6b5c7d0"
}Invalid pagination parameters when page or limit is not a valid number. See Pagination.message is Internal server error, whatever went wrong behind it. The exceptions are two infrastructure failures that return 500 with Database connection error or Redis error, and the throttled-dependency 503 described below. Use errorId to identify the failure when you contact support.{
"status": 500,
"message": "Internal server error",
"errorId": "d41f7e0a-91b3-4a2c-bb6e-5a8c2f9e3d17"
}Internal server error. Rely on the status and errorId.Service temporarily unavailable. Please try again later. rather than a 429.| Status | Meaning | Typical causes |
|---|---|---|
200 | Success. | Some partial successes also return 200, for example Provision Mailboxes with entries in failed. Check the body. |
201 | Created. | Creating a webhook endpoint, a Zap Site or a Zapbox label. |
202 | Accepted for background processing. | Connecting mailboxes with custom OAuth, sending Zapbox mail, deploying or regenerating a Zap Site. |
207 | Multi-status. The call ran but not everything finished or succeeded. | Retry Failed Mailboxes (some domains failed), Connect Domains (names still in progress), Purchase Deliverability Test (some mailboxes not allocated). |
400 | The request is understood but cannot be processed. | Invalid values, a failed business rule, or insufficient wallet balance. |
401 | The API key is missing, malformed, unknown or expired. | See Authentication. |
403 | The key is valid but not allowed to do this. | API access is disabled, or you are not an OWNER or ADMIN of the workspace in x-workspace-key. |
404 | The resource does not exist in the selected workspace. | Unknown domain, mailbox or workspace ID. |
406 | Not acceptable. | Remove Connected Domains when an eligible domain still has mailboxes. Nothing is removed. |
409 | Conflict with the current state. | A provisioning request already running for the workspace, a Google Workspace or Microsoft tenant that already exists for a domain you are buying, or a duplicate workspace, tag or third-party account. |
422 | Validation failed. | See Validation errors above. |
425 | Too early. | Billing details are missing for the workspace. Add them, then retry. |
429 | Too many requests. | The API rate limit, or an endpoint-level throttle. |
500 | Unexpected server error. | The message is masked. |
503 | A dependency is temporarily unavailable. | A third-party provider is throttling or down. |
| Status | Retry? | What to do |
|---|---|---|
400, 401, 403, 404, 406, 422 | No | The request will fail again. Fix the input, key or permissions first. |
409 | Sometimes | For a provisioning request already in progress, wait a few seconds and retry. For other conflicts, change the request. |
425 | After a fix | Add billing details, then retry. |
207 | No | Read the body to see what completed, then handle the remainder. |
429 | Yes | Wait the number of seconds in Retry-After, then retry. See Rate Limits. |
500 | With care | Retry reads with exponential backoff: 1 s, 2 s, 4 s, then stop. For requests that buy something, see below. |
503 | Yes | Retry with exponential backoff, starting at several seconds. |