Error Reference
MCP error codes, what they mean, and how to fix them
When an MCP tool call fails, the response includes isError: true and a structured error object. Your AI tool will typically explain the error and suggest a fix.
Error response format
{
"error": {
"code": "rate_limited",
"message": "Per-minute unit cap exceeded. Slow down.",
"retryable": true,
"retry_after": 12,
"request_id": "01968a3b-..."
}
}Some errors include additional fields:
action_url-- a link to the Atribu dashboard page where you can fix the issueworkspaces-- a list of available workspaces (forworkspace_required)profiles-- a list of available profiles (forprofile_required)support_hint-- a suggestion to contact support with therequest_id
Error codes
Authentication failures
Authentication failures do not return a structured tool error. A missing, malformed, revoked, or expired token gets an HTTP 401 response with a JSON-RPC error (code: -32001, message "Unauthorized: invalid or missing token") and a WWW-Authenticate header. There is no distinct expired-vs-revoked signal.
Fix: check that the request carries Authorization: Bearer atb_user_.... If the token was revoked (or rotated more than 48 hours ago), create a new one from Developer > MCP Tokens.
Scope errors
| Code | Retryable | Cause | Fix |
|---|---|---|---|
workspace_required | No | User has multiple workspaces and none was specified | Pass workspace_id -- the error includes a list of your workspaces |
profile_required | No | Workspace has multiple profiles and none was specified | Pass profile_id -- the error includes a list of profiles |
insufficient_scope | No | Token lacks the required scope for this tool | Create a new token with the needed scope |
Single-resource inference
If you have exactly one workspace or one profile, it's selected automatically. These errors only occur when there are multiple options.
Rate limit errors
| Code | Retryable | Cause | Fix |
|---|---|---|---|
rate_limited | Yes | Per-minute or per-period unit cap exceeded | Wait retry_after seconds, then retry |
The retry_after field tells you how many seconds to wait. AI tools that support retry will handle this automatically.
Connector errors
| Code | Retryable | Cause | Fix |
|---|---|---|---|
connector_expired | No | A required integration's OAuth token has expired | Re-authorize at the action_url in the error response |
connector_required | No | A required integration is not connected | Connect it at the action_url in the error response |
These errors include an action_url that links directly to the integrations page in your Atribu dashboard.
Write-back errors
| Code | Retryable | Cause | Fix |
|---|---|---|---|
writeback_disabled | No | Workspace admin has not enabled MCP write-back | Ask a workspace admin to enable it in Settings > Privacy & MCP |
circuit_open | No | 3+ consecutive failures in the last 30 minutes | Wait for the cooldown, then investigate the underlying failures |
Idempotency replay is not an error
Repeating a confirm with an idempotency key that was already processed returns a success response carrying replayed: true and the prior result — no duplicate send, no error.
Input errors
| Code | Retryable | Cause | Fix |
|---|---|---|---|
invalid_input | No | Invalid or missing parameters | Check the parameter types and required fields |
data_unavailable | Yes | No data exists for the specified window or entity | Widen the date range or verify the entity exists |
Server errors
| Code | Retryable | Cause | Fix |
|---|---|---|---|
internal_error | Yes | Unexpected server error | Retry once. If persistent, contact support with the request_id |
Troubleshooting
"I get workspace_required but I only have one workspace"
This can happen if your token was created before a workspace was deleted. Try calling list_workspaces to see which workspaces your token can access, and pass the workspace_id explicitly.
"Data seems stale or empty"
Check the meta.data_as_of field in successful responses. If it's more than a few hours old, your integration may need re-syncing. Go to Settings > Integrations and check the sync status.
"I can't see customer emails"
PII is masked by default. You need all three: mcp:read_pii token scope, include_sensitive: true in the tool call, and workspace PII mode set to full_default. See Privacy & PII.
"send_meta_conversions returns insufficient_scope"
This tool requires the mcp:write token scope, workspace write-back enabled, and workspace admin role. Check all three conditions.