Errors & troubleshooting
Find the next useful action when a request fails.
API errors carry a stable error code and recovery information such as retryable and action_required. Inspect the returned body instead of relying only on an HTTP status. Keep a request ID when provided so the team can help investigate.
| HTTP status | What to do |
|---|---|
400 | Correct the input. Check required fields and ID formats. |
401 | Check your key, expiry, revocation, and allowed source IPs. |
403 | Check scopes, inbox restrictions, recipient policy, and organization/domain state. |
404 | Refresh the resource from its owning list. Verify you are using the right organization's key. |
409 | Inspect conflict or deletion-pending state. Do not change an idempotency key to conceal a conflict. |
410 | Previously stored content or an idempotency result was removed. Reconcile before recreating anything. |
413 | Reduce message content or page size as appropriate. |
422 | Check suppressed recipients or the lack of a safe reply recipient. |
423 | An attachment is quarantined. Stop; do not bypass the policy. |
429 | Honor Retry-After when present. Preserve the same key for retries. |
500 / 503 | Retry only when safe, with bounded backoff and the original idempotency key. |
I cannot create an inbox
Check GET /v1/me, especially the key's scopes, inbox restrictions, and platformLimits.inboxes. For a managed name conflict, list your inboxes and either recover the existing one or choose a different local part. For a custom domain, verify both inbound and outbound capabilities.
My email was accepted, but I cannot find it
A 202 response is not delivery confirmation. Read the returned submission. If it is delivered, inspect the recipient mailbox's spam filtering. If it is deferred, keep polling within your deadline. Do not create a new logical send to resolve uncertainty.
I do not see incoming mail yet
Confirm the sender used the exact inbox address and that the inbox is active. Allow time for asynchronous processing. List threads and read their messages; checking only the first thread page can miss arrivals. For custom domains, verify MX and inbound capability.
My webhook is not working
Confirm the URL is public HTTPS on port 443 and does not redirect. Verify your secret, raw-body handling, and system clock. Ensure your receiver persists the event and returns a 2xx response. Reconcile the inbox through polling while investigating.
Contact the Mailactor team if you need a key or organization-policy change.