errors

Ayrshare MCP — Errors

One tool, the canonical way to decode any Ayrshare error code:

• mcp__ayrshare__explain_error — looks up an error code in the Ayrshare error catalog and returns a plain-English cause, a classification, and a short resolution hint.

It is the cross-cutting helper every other group skill points to: when a tool call fails with a structured error code (e.g. Error 156: ...), translate it here before surfacing anything to the user.

Functions

Tool	Purpose	Method + Endpoint	Required inputs	Optional inputs
mcp__ayrshare__explain_error	Explain an Ayrshare error code from the canonical error catalog	GET /error-explainer	code (string of digits, or a number)	platform (a platform identifier)

The response gives three things:

• Cause — a plain-English description of what went wrong.
• Classification — one of developer-fix (your code/config/input is wrong), user-action (the end user or their linked account must act, e.g. re-auth, permissions, content rules), or network (a transient/platform-side issue).
• Resolution hint — a short suggested fix.

The classification is derived from the error's HTTP status, not from the meaning of the message: 401/402/403 → user-action, 5xx → network, and every other 4xx (including 400) → developer-fix. So a relink-required error such as 156 ("…is not linked") or 272 (X/Twitter authorization issue) — both HTTP 400 — is labeled developer-fix even though the real fix is an end-user relink. Treat the label as a coarse routing hint and always read the cause and resolution text; a developer-fix can still carry an instruction meant for the end user.

Auth

This tool is reached over the same authenticated connection as every other Ayrshare MCP tool. explain_error is account-level: it decodes an error code and does not take a profileKey argument (it is one of the few tools excluded from per-call profile selection). Its only inputs are code and platform (no passthrough object). See Which tools accept profileKey in ../getting-started/SKILL.md.

Usage guidance

• This is the first stop after ANY failed tool call. When create_post, add_comment, get_platform_history, or any other Ayrshare MCP tool returns a structured error code (e.g. Error 156: ...), call explain_error with that code (pass the failing platform if you have it) and surface the explanation. Do not echo the raw error or guess at the meaning.
• Pass platform when you have it. The same numeric code can mean different things per network; supplying the platform identifier (e.g. the platform that the failed call targeted) sharpens the cause and fix.
• code accepts a string of digits or a number. Pass the bare code from the error (e.g. 156, "272"). Strip any surrounding text.
• Act on the classification:
  • developer-fix → usually the input/config/code is wrong; fix it before retrying (do not blindly re-call the failing tool). But because this bucket is just "a 4xx that isn't 401/402/403", it also catches end-user issues that happen to return 400 (e.g. an account relink, like codes 156/272) — read the resolution and relay it to the end user when that is what it says.
  • user-action → the end user or their linked social account must do something (re-authenticate, grant a permission, change content); relay the resolution hint to them.
  • network → transient/platform-side; a single retry after a short delay is reasonable (matching the global 429/transient rule), but don't loop.
• It does not fix the underlying call. explain_error only decodes the code. After understanding it, address the root cause and re-run the original tool deliberately — don't auto-retry the failed write.

Gotchas

• Don't echo raw error codes at the user. A bare Error 272 is unhelpful. Always run it through explain_error and present the cause + fix.
• The classification drives whether a retry is even sensible. A developer-fix or user-action error will not resolve on retry — only network-class errors warrant the single transient retry. Never auto-retry a failed write on a 4xx just because you decoded it.
• Provide platform for accuracy. Omitting it still works but may give a more generic explanation when the code is platform-specific.
• explain_error takes no profileKey argument. It is account-level (one of the few tools excluded from per-call profile selection); the profile-scoped tools do accept a profileKey argument (see getting-started).
• explain_error is itself a read. If the lookup call fails (rare), surface it plainly; don't loop. (Mirrors the global retry-safety rule in ../getting-started/SKILL.md.)