// troubleshooting

Reading errors

The shapes a failure takes over REST and over MCP, where the error code sits in each, and which failures are safe to retry.

superagnt_ answers on two surfaces: REST at https://api.superagnt.com and MCP at https://mcp.superagnt.com/mcp. Each reports a failure in its own shape, but the codes are the same on both. This page shows every shape and where to find the code in it.

REST: one envelope

Every REST response is success: true with the payload under data, or success: false with a single error object. There is no third shape, and no endpoint returns a bare payload.

failurejson

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "1 validation error in request",
    "details": [
      { "field": "username", "location": "query", "message": "Required" }
    ]
  }
}

These fields appear only when they apply:

Field	When it is there	What it tells you
`error.details`	`VALIDATION_ERROR`	One entry per bad field: `field`, `location` (`query`, `path` or `body`), `message`, and sometimes `expected`.
`error.retryAfter`	`RATE_LIMITED`, and other failures where waiting is the fix	Seconds to wait. The same number is sent as the `Retry-After` header.
`error.upgrade`	`PLAN_REQUIRED`, `PLAN_LIMIT_REACHED`, `DATA_CREDITS_EXHAUSTED`	The upgrade offer to relay to a person. See Plan limits and upgrade offers.
`error.billingPortalUrl`	`SUBSCRIPTION_PAST_DUE`	Where a person updates the payment method.
`how_to_get_access`	A 401 on any `/v1/*` path	The MCP endpoint, signup, docs and OpenAPI URLs, for a caller that has no credentials yet.

MCP: a tool error

The call reached the tool and the tool failed. The JSON-RPC response itself succeeds, and the tool result carries isError: true:

tool errorjson

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "1 validation error in request\n\nError details:\n{ ...the structuredContent below... }"
      }
    ],
    "structuredContent": {
      "code": "VALIDATION_ERROR",
      "message": "1 validation error in request",
      "error": "VALIDATION_ERROR",
      "details": [
        { "field": "username", "location": "query", "message": "Required" }
      ]
    }
  }
}

Read structuredContent when your client gives it to you. When it does not, the same JSON is printed after Error details: in the text.

structuredContent.code is the same code REST would return for the same failure.
structuredContent.error is the most specific name for what went wrong. For most failures it equals code. For a connection that is not set up it is INTEGRATION_NOT_CONNECTED, for a grouped tool called wrong it is MISSING_ACTION, UNKNOWN_ACTION, MISSING_REQUIRED or INVALID_ARGUMENTS, and for a tool your kind of caller may not use it is FORBIDDEN.
A connection failure also carries providerId, providerName, upstreamStatus and upstreamError, the vendor's own error. See Connection failures.

MCP: a plan refusal is not an error

When your plan stops a call (out of included data credits, at a cap, trial ended, over the per-minute limit), the tool returns a normal, successful result whose content is the upgrade offer:

plan refusaljson

{
  "status": "requires_upgrade",
  "reason": "limit_reached",
  "message": "...one sentence naming the next plan...",
  "confirm_url": "https://app.superagnt.com/confirm/<token>",
  "human_step": "...what to tell the person you work for..."
}

It is a result on purpose, so your client hands it to you instead of hiding it as a failure. Nothing ran and nothing was charged. Relay human_step and the confirm_url to a person. The full offer is on Plan limits and upgrade offers.

MCP: a protocol error

The request never reached a tool. The JSON-RPC response has an error object and no result:

JSON-RPC code	Message	What it means
`-32001` (with HTTP 401)	`Missing Authorization header`, `Invalid MCP server token`, `MCP OAuth token expired`, and similar	The connection is not authenticated. See MCP connection and auth.
`-32601`	`Unknown tool '<name>'`	This server does not serve that tool to you: it is not enabled, the name is wrong, or your client's tool list is out of date.
`-32602`	`Missing tool name`	A `tools/call` without `params.name`.
`-32600`	`Invalid Request`	The body is not JSON-RPC 2.0.
`-32603`	varies	An unexpected failure while a streamed tool call was running. Retry once.

What is safe to retry

Code	Retry?
`RATE_LIMITED`	Yes, after `retryAfter` (REST) or `retry_after_seconds` (MCP) seconds.
`PROVIDER_UNAVAILABLE`, `UPSTREAM_CREDITS_EXHAUSTED`, any HTTP 502 or 503	Yes, with backoff.
`INTERNAL_ERROR`	Once, with backoff. If it repeats, open a ticket.
`VALIDATION_ERROR`, `ENDPOINT_NOT_FOUND`, `NOT_FOUND`, `CONFLICT`	No. Change the call first.
Any 402, or a `requires_upgrade` result	No. A person has to top up or confirm a plan.
`UNAUTHORIZED`, `INTEGRATION_NOT_CONNECTED`	No. A credential or a connection has to be fixed first.

The complete list of codes and their HTTP statuses is on Errors and rate limits.