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 |
402 budget_exhausted |
The AI allowance refused the call. reason: exhausted (month used), would_exceed (this call would pass it), disabled (AI off for the account), new_account (starter allowance until HubSpot is connected), email_unverified (nobody on the account has confirmed an email yet) |
Wait for the month, ask support to raise it, connect HubSpot, or confirm the email in the app |
403 key_suspended · key_revoked |
The key was suspended or revoked in the app | Account → API; make or rotate a key |
403 account_suspended |
The account is suspended | Contact support |
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 forbidden_scope "Not available on the public API - use the app" |
Deleting a positioning framework, or a write on a read-only resource (/activity) |
Use the app |
404 not_found "Not available on the public API" |
Internal or owner-only routes (site-key rotate, scheduler runs, provisioning) | Use the app |
409 conflict |
State forbids it (reveal a show-once key, rotate a revoked key) | Read message |
409 has_associations |
Deleting a hub, template or block kind that still has dependents | Remove each item in error.associations, then delete |
| 413 | Body over 1 MB | Use media endpoints for files; split writes |
429 rate_limited |
Burst, per-minute, account ceiling, or 30 ai.write calls a minute per account |
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 |
In the app (not the API), sessions can also see mfa_required (the account requires two-factor and
this person has not turned it on: Profile, Security), agency_scope (an agency working inside a
client account changed something only the client may change) and session_invalid (signed out).
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.
"An imported article shows the day I imported it as Created." The record's
stamps are set when the row is written unless you send them. PUT /hubs/articles/{id} with { "created_at": "2020-03-01", "published_at": "2020-03-01" } back-dates it in place (MCP: update_article). display_date
is the separate date readers see.
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.