Skip to content

Errors

REST calls answer with an error string. MCP calls answer with a JSON-RPC error object. Upstream messages from the social networks are passed through untouched so you can act on them.

On this page
  1. Error shapes
  2. Errors you will meet
  3. Partial success

Error shapes

REST · error
{
  "error": "API Request failed with status 402"
}
MCP · JSON-RPC error
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "API Request failed with status 402"
  },
  "id": 1
}

The HTTP status on a REST error is the one the tool router chose, and the message carries the upstream reason where there is one. MCP clients surface the JSON-RPC message to the model, which is usually enough for it to recover on its own.

Errors you will meet

400Tool not found

The tool name in the path does not match one of the published tools.

Fix: Check the path spelling — names are snake_case and case-sensitive.

400No valid session ID provided

An /mcp request arrived without an Mcp-Session-Id and was not an initialize call.

Fix: Start the session with an initialize request, then send the returned session id on every follow-up.

500Missing POSTMCPAI_API_KEY

No key was found in the header, the Authorization bearer token, or the apikey query parameter.

Fix: Set POSTMCPAI_API_KEY in the server environment, or pass the key per request.

500Upstream API message

The PostMCP backend rejected the call — expired channel authorisation, exhausted credits, or invalid payload.

Fix: The upstream message is passed through verbatim in error. Re-connect the channel or top up credits as it indicates.

Partial success

A post fans out to several profiles, and each one can fail on its own: a revoked authorisation, a duplicate-content rejection, an unsupported media type. The envelope can be a 200 with status: "published" while one profile failed.

Read targets[] on the post rather than the envelope. Each entry carries its own status and, when it went wrong, the reason.

list_posts · targets[]
[
  {
    "platform": "linkedin",
    "profileId": "lin_7741903",
    "status": "published",
    "postId": "urn:li:share:7218..."
  },
  {
    "platform": "twitter",
    "profileId": "tw_1293847",
    "status": "failed",
    "error": "Duplicate content rejected by upstream"
  }
]