Errors catalogue
Every Simp Connect tool error code with its teaching message and what the agent should do next, generated from the live catalogue.
A failure inside a tool is an in-band tool error: the JSON-RPC response is a result with isError: true, and its text content is JSON with a machine-readable error code plus a teaching message that names the field, the constraint and a valid example where one exists. Your agent can read it and correct itself.
{
"error": "invalid_respond_by",
"message": "respond_by needs a time zone offset ('Z' or '+hh:mm'): a time without one is ambiguous. For example '2026-10-07T18:00:00+01:00'."
}Failures outside a tool are protocol errors (JSON-RPC error, with an HTTP status):
| HTTP | JSON-RPC code | When |
|---|---|---|
| 401 | -32002 | No token, or an expired, revoked or wrong-audience token. WWW-Authenticate points at the protected resource metadata. |
| 403 | -32001 | The token lacks the scope the tool needs (WWW-Authenticate names it). |
| 403 | -32600 | The request carried a browser Origin Simp does not allow. |
| 415 | The body is not application/json. | |
| 400 | -32020 | A routing header (Mcp-Method, Mcp-Name) disagrees with the body. |
| 400 | -32021 | A tasks/* method without the tasks extension declared in clientCapabilities. |
| 400 | -32022 | An unsupported MCP-Protocol-Version (including initialize); data.supported lists 2026-07-28. |
| 404 | -32601 | A method Simp does not serve. |
| 400 | -32602 | Invalid params, an unknown tool, or an unknown task id. |
| 405 | GET or DELETE on the endpoint: there is no session and no stream to open or close. |
This catalogue is generated from the same source as the Tool reference (reference version 2). Angle-bracketed parts of a message (<scope>, <n>) are filled in at runtime.
Errors any tool can return#
| Code | Message (as returned) | What the agent should do next |
|---|---|---|
unauthorized | No authenticated Simp user on this connection. | The OAuth token is missing or invalid. Reconnect Simp (OAuth). |
insufficient_scope | insufficient_scope: this tool requires the <scope> scope, which this connection was not granted. | Ask the user to reconnect Simp granting the named scope. |
rate_limited | Rate limit exceeded (<limit>). Wait <n> seconds and try again. | Back off for retry_after_seconds, then retry. |
invalid_arguments | The arguments do not match <tool>'s schema: <field>: <rule>. | Fix the named field and resend. |
Errors from support_ask#
Returned by support_ask.
| Code | Message (as returned) | What the agent should do next |
|---|---|---|
verification_required | Log in to the app and I'll pick this up with your account in front of me. | Relay to the user: account changes happen in the Simp app, never from here. |
Errors from support_ask, support_cases#
Returned by support_ask, support_cases.
| Code | Message (as returned) | What the agent should do next |
|---|---|---|
support_unavailable | <reason> | Retry once; if it persists, tell the user to open the Simp app. |
Errors from create_task#
Returned by create_task.
| Code | Message (as returned) | What the agent should do next |
|---|---|---|
plan_no_mcp | Agent integrations aren't included in the user's Simp plan ... | Relay to the user; they can upgrade their plan. |
invalid_participants | Each participant needs one of phone, email, handle or party_id. / A call task has exactly one participant ... / A call needs a phone number ... | Confirm who with the user and resend. Never guess a number. |
invalid_respond_by | respond_by is required for this kind ... / respond_by is for get_answer, send_update and follow_up ... / Give them at least an hour to answer. / Choose a deadline within the next two weeks. | Send respond_by (ISO 8601 with offset, 1 hour to 14 days) for answer tasks; drop it for a call. |
invalid_options | options are for get_answer and follow_up ... | Drop options for a call or a send_update. |
invalid_boundaries | A call task always phones, so may_call cannot be false ... | Use get_answer or send_update if the user does not want a call. |
no_route_without_a_call | Simp reaches people for this user by phone call only, so a task with may_call false cannot reach anyone ... | Ask the user whether a call is acceptable. |
participant_not_known | <name> is not someone the user already knows, and known_contacts_only is set ... | Ask the user, or drop the boundary. |
question_invalid | Your question includes a phone number or link ... / Keep each answer under 40 characters. / ... | Reword the objective or the options as the message says. |
no_number | The user doesn't have a Simp virtual number set up yet. | Ask the user to finish setting up Simp. |
unknown_persona | persona "<value>" is not one of the user's simps. Use one of: <names> ... | Pick a name or id from get_user_info, or omit persona. |
unknown_number | from_number "<value>" is not one of the user's AI-capable Simp numbers. Use one of: <numbers> ... | Pick a number or id from get_user_info, or omit from_number. |
ai_minutes_cap_reached | You've reached your monthly <n>-minute AI calling limit ... | Relay to the user; get_user_info.can_create_tasks pre-empts this. |
internal_cap_reached | You've reached your internal test cap. Contact your admin to raise it. | Internal test accounts only - contact the Simp admin. |
account_config_invalid | This account cannot place calls right now. | Internal test accounts only - contact the Simp admin. |
destination_not_allowed | <number> is a premium-rate / emergency number ... or Simp's calling policy does not allow calls to <number> on this account. | Use a standard geographic or mobile number; never retry the same destination. |
connection_frozen | This connection was paused by Simp after an unusual pattern ... | Ask the user to re-enable the connection under Connected apps in the Simp app. |
connection_daily_cap_reached | This connection has created <n> tasks today, which is its daily limit (<cap>) ... | Try tomorrow, or ask the user to change the connection mode. |
sandbox_limit_reached | This account has used its 3 sandbox calls for today ... / This app has reached its daily sandbox allowance ... | Try tomorrow, or call a real number the user owns. |
sandbox_unavailable | The Simp sandbox is busy right now - try again shortly. | Retry shortly (the sandbox fails closed on capacity checks). |
sandbox_calls_only | The sandbox test number answers calls only: create it as kind call. | Use kind call for the sandbox number. |
task_creation_failed | <database message> | Retry once; if it persists, report it. |
Errors from get_task, respond_to_decision, cancel_task, get_user_info#
Returned by get_task, respond_to_decision, cancel_task, get_user_info.
| Code | Message (as returned) | What the agent should do next |
|---|---|---|
not_found | No task with that id on this account. | Use a task_id from create_task or list_tasks. |
Errors from respond_to_decision#
Returned by respond_to_decision.
| Code | Message (as returned) | What the agent should do next |
|---|---|---|
not_awaiting_input | This task is not waiting on the user (current state: <state>). Call get_task for the latest state. | Re-read the task; the decision may already be answered. |
unknown_decision | decision_id does not match the pending decision on this task. Use the decision_id from get_task. | Re-read pending_decisions and resend with its decision_id. |
wrong_answer_type | This decision is an approval: pass approve true or false. / This decision asks for information: pass the user's response as text. | Send the answer the decision type asks for. |
answer_missing | Pass the user's answer ... (Your client did not declare form elicitation ...) | Ask the user and send approve or response. |
invalid_request_state | That retry does not match the question Simp asked. Call respond_to_decision again. | Start the round again without requestState. |
resume_failed | <reason> | Check the task; the call may have ended. |
Errors from cancel_task#
Returned by cancel_task.
| Code | Message (as returned) | What the agent should do next |
|---|---|---|
not_cancellable | This task can no longer be cancelled (current status: <status>). | Nothing to do - the task is already terminal. |
Handling errors well#
- Read the message. It is written for the agent: it says what was wrong and usually shows a valid value. Relay the human-relevant part to the user; do not retry blindly.
- Never retry
destination_not_allowedorinvalid_participantswith the same number. Confirm the number with the user. rate_limitedcarriesretry_after_seconds. Wait that long.connection_frozenandconnection_daily_cap_reachedare resolved by the user in the Simp app (Connected apps), not by your agent.sandbox_limit_reached/sandbox_unavailablemean nothing was created; try again tomorrow or use a real number the user owns.not_awaiting_input,unknown_decision,wrong_answer_type: callget_taskagain and use thedecision_idandtypeit returns now. The earlier decision is answered or stale.invalid_request_state: the signedrequestStateof a multi round-trip retry was altered, expired (10 minutes) or belongs to another call. Callrespond_to_decisionagain from the start.insufficient_scope(or HTTP 403-32001): the connection was granted without that scope; the user needs to reconnect and grant it.