Troubleshooting
Error codes
| Status · code | What happened | What to do |
|---|---|---|
400 bad_request |
The body or query failed validation | Read message; it names the field |
401 unauthorized |
No credential, malformed, revoked, or unknown | Check the Authorization header; verify with /me |
401 key_expired |
Past expires_at (grace over, if rotated) |
Rotate or create a key |
403 forbidden_scope |
Scope missing, or the route is app-only | /me shows your scopes; app-only routes are listed in the reference |
403 browser_origin |
API key sent from a browser | Move the call server-side, or use OAuth |
403 ip_not_allowed |
Key has an allowlist and you are not on it | Account → API → Settings for that key |
404 not_found |
No such object in your account | Ids from another account look identical to nonexistent ones — on purpose |
405 bad_request "Not available on the public API" |
Owner action (hub delete, identity delete, site-key rotate, scheduler runs) | Use the app |
409 conflict |
State forbids it (reveal a show-once key, rotate a revoked key) | Read message |
| 413 | Body over 1 MB | Use media endpoints for files; split writes |
429 rate_limited |
Burst, per-minute, or account ceiling | Honour Retry-After; see rate limits |
429 enrollment_cap |
Hourly enrollment cap | Honour Retry-After |
502 upstream_error |
A service behind the API did not answer or failed | Retry with backoff; quote reference if it persists |
503 with Retry-After |
Transient (only on the HubSpot action path) | HubSpot retries automatically; API callers should too |
Symptoms
"My key worked yesterday and returns 401 today." It was revoked or
rotated in the app, or it expired. /me with the old key says which; check
Account → API for its status.
"I get 200 but data is empty." You are looking at another account's
ids, or the filter excludes everything. Check /me → account_id against
where the object lives. Agencies and their clients are separate accounts.
"X-MXA-Key-Status: rotated_grace in responses." Something still uses a
rotated key. Find it before the grace period ends.
"Webhook deliveries show failed." Your endpoint returned non-2xx or
took over 10 s. GET /webhooks/{id}/deliveries shows the HTTP code and
error per attempt. After 20 consecutive failures the endpoint pauses;
resume it once fixed.
"The MCP client lists fewer tools than the docs." The token lacks the
scope; tools/list is filtered to what the token can call.
"simulate shows 0 steps." The campaign has no enabled pool with
messages, or the contact fails every pool's filter. The response's per-step
reason says which.
Status and health
https://api.mxaura.ai/v1/health— API uphttps://mcp.mxaura.ai/health— MCP up, versionshttps://api.mxaura.ai/v1/openapi.json— the current contract
Quote the reference from any 5xx when you contact support.