Troubleshooting
What to do when a superagnt_ call fails. How to read the error, which page covers it, and when to ask the team for help.
These pages are written for an AI agent that just hit a failure while working for someone, and for the person reading over its shoulder. Each one starts from what the failed response looks like and ends with what to do next.
01
Read the error before you retry
Every failure names itself with a stable code. Read the code, not the message: messages are written for people and can change, codes are a contract. Where the code sits depends on how you called:
| How you called | Where the failure is | What to read |
|---|---|---|
REST, https://api.superagnt.com/v1/... | the response body, with success: false | error.code and error.message, plus error.details, error.retryAfter or error.upgrade when present |
An MCP tool at https://mcp.superagnt.com/mcp | a tool result with isError: true | structuredContent.code or structuredContent.error, and structuredContent.message. The same text is in content[0].text. |
| An MCP tool your plan refused | a normal tool result, not an error | status: "requires_upgrade", reason, human_step and confirm_url |
| The MCP connection itself | an HTTP 401 or 403 before any tool runs | the JSON-RPC error.message and the WWW-Authenticate header |
Every shape is shown in full on Reading errors.
02
Three rules that cover most failures
- A 400 (
VALIDATION_ERROR) is your request. Fix the arguments. Sending the same call again gets the same answer. - A 402 means a person has to act: top up, or confirm a plan. Never retry a 402 on a timer. The balance and the plan do not change on their own.
- A 429 or a 503 means wait. Honour
retryAfter(or theRetry-Afterheader), back off, then retry.
A call that fails is not billed, including one that failed after the upstream provider was already asked.
03
Find the page for your error
| You saw | Go to |
|---|---|
INSUFFICIENT_CREDITS, DATA_CREDITS_EXHAUSTED, UPSTREAM_CREDITS_EXHAUSTED, AI credits exhausted | Credits and 402s |
PLAN_REQUIRED, PLAN_LIMIT_REACHED, status: "requires_upgrade", SUBSCRIPTION_PAST_DUE | Plan limits and upgrade offers |
RATE_LIMITED, HTTP 429 | Rate limits |
HTTP 401 or 403 from the MCP endpoint, Unknown tool, tools missing from your list | MCP connection and auth |
INTEGRATION_NOT_CONNECTED, a connect_url, a vendor 401, 403 or 429 | Connection failures |
VALIDATION_ERROR with details, ENDPOINT_NOT_FOUND, PROVIDER_ERROR | Data source errors |
| Anything else, or nothing here helped | Getting help |
The complete code table, with every HTTP status, is on Errors and rate limits.
04
When to ask for help
Search the docs first with agnt_support_docs_search. It returns the matching sections of these pages and the rest of the docs, each with a link when the page is published on superagnt.com.
If the answer is not there, or the docs say the failure is on our side and it keeps happening, open a ticket with agnt_support_ticket_create. A person on the superagnt_ team reads every ticket and replies on it, and the workspace owner gets the reply by email too. Read the answer with agnt_support_ticket_get. How to write a ticket that gets answered fast is on Getting help.
never send secrets
Never put an API key, an OAuth token, a password or a connection credential in a ticket. The team never needs one to help you.
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.
Credits and 402s
Which 402 you got and what to do about it. INSUFFICIENT_CREDITS versus DATA_CREDITS_EXHAUSTED, the trial data credit, AI credits for deployed agents, and why UPSTREAM_CREDITS_EXHAUSTED is a 503.
Plan limits and upgrade offers
What a requires_upgrade offer contains, every reason it can carry, how to hand the confirm_url to a person, and what still works when a plan has lapsed.
Rate limits
How the per-minute limit is counted, what a 429 looks like over REST and over MCP, and the 429s that come from a vendor rather than from superagnt_.
MCP connection and auth
Fixing 401s and 403s from the MCP endpoint, expired or invalid tokens, OAuth that will not finish, and tools that do not show up until the client refreshes.
Connection failures
What INTEGRATION_NOT_CONNECTED and its connect_url mean, and what to do when a vendor you connected with your own credential rejects a call with a 401, 403, 429 or 5xx.
Data source errors
Why a data source call was rejected and how to fix it. Argument validation details, unknown endpoints and sources, upstream failures, cost caps, and why an empty result is not an error.
Getting help
Search the docs with agnt_support_docs_search, then file a support ticket with agnt_support_ticket_create. What to put in the subject, body and context, how to read the team's reply, and what never to send.