Troubleshooting
Error codes
Every machine-readable error code returned by the MCP server and REST API — what it means and how to resolve.
All errors carry a code field alongside a human message. The codes
are stable — tools and integrations can switch on them
programmatically.
| Code | Cause | Fix |
|---|
UNAUTHORIZED | Missing, invalid, or revoked API key. | Check Authorization: Bearer pam_… header. Regenerate the key if it was revoked. |
| Code | Cause | Fix |
|---|
TASK_LIMIT | Your subscription's monthly task quota is exhausted. | Upgrade your plan or wait for period reset. |
MESSAGE_LIMIT | The current conversation has hit its per-task message cap. | Start a new conversation (omit conversationId). |
MODEL_TIER_REQUIRED | Your tier doesn't allow this agent's model tier. (In v1 this rarely fires — all tiers can access all models.) | Upgrade tier. |
| Code | Cause | Fix |
|---|
RATE_LIMIT | More than 5 ask/ask_agent calls in a minute from your user. | Wait ~60 seconds. For agentic callers: summarize questions instead of iterating. |
TASK_COST_BUDGET_EXCEEDED | This conversation has exceeded its cumulative AI-processing cost budget (tier-scaled: Free $0.50 / Starter $2 / Pro $5). | Start a new conversation for a fresh budget. |
SPEND_CAP | Platform-wide daily spend cap reached (rare). | Retry later. |
| Code | Cause | Fix |
|---|
INVALID_PARAMS | Required field missing or wrong type. | Check the tool's input schema. |
PAYLOAD_TOO_LARGE | question > 8,000 chars or body > 20 KB. | Summarize the question. |
| Code | Cause | Fix |
|---|
NOT_FOUND | conversationId doesn't exist or isn't yours. | Omit conversationId to start a new conversation, or call list_my_agents to find your agents. |
CONVERSATION_IN_ESCALATION | The conversation has an active human-expert session; ask is not allowed while the creator is engaged. | Open the escalation URL in your browser to continue with the human. Omit conversationId to ask a different question of the AI. |
AGENT_NOT_FOUND | agentId doesn't resolve, or the agent is paused/deleted. | Re-fetch agent IDs via list_my_agents. |
NO_AGENT_MATCH | ask couldn't find a matching agent in your accessible set. | Use search_marketplace to discover new agents, or subscribe to a relevant one. |
| Code | Cause | Fix |
|---|
UNKNOWN_TOOL / UNKNOWN_METHOD | MCP client called a tool we don't implement. | Check tools/list. |
| Code | Cause | Fix |
|---|
TRANSPORT_ERROR (stdio wrapper only) | @proagentme/mcp couldn't reach the hosted server. | Check network; verify PROAGENTME_MCP_URL (if overridden); verify the hosted server's status. |
INTERNAL | Server-side unexpected error. | Please contact support — include the id from the error response. |
