Error Handling

Error format

Errors follow the standard MCP tool response format. Tools return errors like this:

{
  "isError": true,
  "content": [{ "type": "text", "text": "{\"error\":\"AUTH_REQUIRED\",\"status\":401,\"message\":\"...\"}" }]
}

Error codes

Code
Status
Meaning

AUTH_REQUIRED

401

Session expired or missing

insufficient_scope

403

Bearer token lacks required scope

RATE_LIMIT

429

Too many messages

BLOCKED

403

Recipient blocked you

POLICY_BLOCKED

403

DM not allowed by platform policy

COOLDOWN

403

Temporary protection when sending too quickly to the same recipient

INVALID_INPUT

400

Bad parameters

NOT_FOUND

404

Conversation or user not found


Rate limits

  • 200 messages per hour per wallet

  • Applies to send_dm only (read and identity tools are unlimited)

  • RATE_LIMIT error returned when exceeded


Retries

  • Safe to retry on AUTH_REQUIRED — re-authenticate, then retry

  • Do NOT retry BLOCKED or POLICY_BLOCKED — permanent for the given recipient

  • Wait before retrying RATE_LIMIT or COOLDOWN — respect the limit window

  • send_dm deduplicates via clientMsgId (an optional client-generated identifier for deduplication) — safe to retry on network errors, but do not assume exactly-once delivery

  • Read and identity tools are safe to retry without side effects

Last updated