Error Reference

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 response

{
  "error": {
    "code": "rate_limited",
    "message": "Per-minute unit cap exceeded. Slow down.",
    "retryable": true,
    "retry_after": 12,
    "docs_url": "https://www.atribu.app/docs/mcp/errors#rate_limited",
    "request_id": "01968a3b-..."
  }
}

Every error carries docs_url -- a deep link back to this page, to the exact code you got. Some errors include additional fields:

docs_url -- a deep link to the section on this page for this exact code
required_scopes -- present on insufficient_scope when the missing token scope is known by name
action_url -- a link to the Atribu dashboard page where you can fix the issue
workspaces -- a list of available workspaces (for workspace_required)
profiles -- a list of available profiles (for profile_required)
support_hint -- a suggestion to contact support with the request_id

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, or re-consent with a wider one
`insufficient_role`	No	Your ROLE in the workspace is too low for this write (#1058)	Ask a workspace owner/admin to run it, or to raise your role in Settings > Members. Re-consenting with a wider scope cannot fix a role, and the approval hand-off does not cover the setup tools — see below

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 — workspaces an `mcp:write` agent created start with it on, so this only fires for a console- or app-created workspace, or one an `mcp:read`-only token made. It gates EVERY write tool, not only the CAPI export	Ask a workspace owner/admin to enable it in Settings > Privacy & MCP. Reads and every write tool's `preview` mode keep working meanwhile
`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.

"An onboarding write is refused and I do not know which of the three is missing"

The three gates answer with three different codes, on purpose — each has a remedy the other two cannot supply:

Code	What is missing	Who fixes it
`insufficient_scope`	the token's `mcp:write` grant	you, by re-consenting
`writeback_disabled`	the workspace's MCP write-back setting	a workspace owner/admin, once
`insufficient_role`	your owner/admin role	a workspace owner/admin

Why an approval hand-off does not rescue the third one. apply_recommendation and send_meta_conversions let a non-admin propose a write for a human to approve, because the approved write runs later, server-side, through a function Atribu already owns. An onboarding tool's write exists only as a REST call carrying your token — there is nothing to run later without either storing your credential or re-implementing the write with different authorization. So for the setup tools the answer is the honest one: someone who holds the role has to run it.

Every one of them carries an action_url pointing at the exact page. Run the tool with mode: "preview" to see what the call WOULD do — preview clears none of these gates, deliberately, so you can show a user the plan before asking them to change anything.

Error response format

Error codes

Authentication failures