Errors - Sumvin

Every error Sumvin returns carries a short code, so an agent or a person can tell one failure from another without parsing prose. This page covers the codes you can meet through the MCP connector and the account setup it depends on. It isn’t the full list Sumvin’s systems use internally.

Reading a code

A code has three parts, and sometimes a fourth: DOMAIN-STATUS-SEQUENCE, then -R if the failure is worth retrying.

MCP-401-001: the area (MCP), the HTTP status it came with (401), and which failure in that area (001). No -R, so it’s terminal: sending the same request again gets the same answer. Something has to change first: the credential, the input, a setting.
MCP-429-001-R: ends in -R, so it’s retryable: the same request, sent again after a short wait, can succeed without anything changing. Honour retry_after when the error carries one, and back off between attempts.

That’s the whole rule, so a client can decide without a lookup table: retry when the code ends in -R, stop otherwise.

What an error looks like

A tool call that fails comes back as an error result. Its text leads with a message written for the agent, followed by the same error as JSON, and the JSON is also the result’s structured content:

{
  "code": "KYC-503-002",
  "title": "Verification at daily capacity",
  "detail": "Identity verification has reached today's capacity. Wait for the daily allowance to reset at 00:00 UTC.",
  "retryable": false,
  "retry_after": 5400,
  "trace_id": "0af7651916cd43dd8448eb211c80319c",
  "_links": {
    "docs": {
      "href": "https://docs.sumvin.com/reference/errors#kyc-503-002"
    },
    "sumvin:skill": {
      "name": "sumvin-sigil",
      "href": "skill://sumvin-sigil/references/errors.md#limits",
      "tool": "sumvin_guide",
      "args": {
        "name": "sumvin-sigil",
        "file": "references/errors.md"
      },
      "why": "Which limits exist and what to tell the person."
    },
    "next": {
      "tool": "kyc_start",
      "args": {}
    },
    "support": {
      "href": "https://docs.sumvin.com/support"
    }
  }
}

code, title and detail say what went wrong. detail is specific to this call.
retryable is true exactly when the code ends in -R. retry_after is the number of seconds to wait when the error names one, and null otherwise.
trace_id identifies this call in Sumvin’s logs. Quote it with the code if you contact support.
_links.docs is this code’s entry on this page. _links["sumvin:skill"] names the guide to load, with the sumvin_guide call that loads it. _links.next, when present, is the call most likely to move things on. _links.support is how to reach Sumvin.

Refused before the tool runs

Some refusals happen at the connection, before any tool runs, and arrive as an HTTP status with a problem body rather than as the error above. Each has its entry below:

MCP-401-001
MCP-429-001-R
MCP-429-002-R
MCP-503-001

The rest of this page groups the codes by the kind of fix they call for.

Retryable

Nothing about the request was wrong. Wait for retry_after seconds when it is set, or a few seconds when it is not, then send the same call again. Back off between attempts and stop after a few.

`KYC-429-003-R`

Too many verification links this hour. The person has asked for as many verification links as an hour allows. Have them finish with the latest link if it is still open; otherwise wait for retry_after.

`KYC-503-003-R`

Verification briefly unavailable. Identity verification could not confirm its capacity just now. Wait for retry_after and call again.

`MCP-429-001-R`

Too many requests from this connection. Wait for the Retry-After time, then send the same request again.

`MCP-429-002-R`

Too many requests from this network address. Wait for the Retry-After time, then send the same request again.

`MCP-503-002-R`

Guide temporarily unavailable. The guide could not be loaded just now. Try again in a minute, and carry on without it if it is still missing.

`MCP-503-003-R`

A service Sumvin depends on is busy. A service behind this tool timed out or asked Sumvin to slow down. Wait a few seconds and send the same call again.

`MCR-503-002-R`

Approval check briefly unavailable. The approval could not be checked just now. It clears on its own; check the outcome with mandate_status in a minute.

`UST-503-001-R`

Strategy schedule not updated. The schedule could not be saved just now. Wait a moment and send the same call again.

`WAL-409-002-R`

Primary wallet changed at the same time. Another change to the primary wallet landed first. Wait a moment and send the same call again.

`WAL-409-003-R`

Wallet still being set up. The smart wallet is still being set up. Wait a minute and send the same call again.

Auth

This connection has no credential Sumvin accepts. Ask the person to connect their Sumvin account to this app; retrying the call will not change the answer.

`MCP-401-001`

Account not connected. This connection has no Sumvin account behind it. Ask the person to connect their Sumvin account to this app, then carry on with what they asked.

`MCR-401-001`

Approval needs a signature. This is answered on the person’s approval page, not to you. Tell them what it says and let them finish there; check the outcome with mandate_status.

`MCR-401-002`

Approval signer not recognised. This is answered on the person’s approval page, not to you. Tell them what it says and let them finish there; check the outcome with mandate_status.

`MCR-401-003`

Approval signer not registered. This is answered on the person’s approval page, not to you. Tell them what it says and let them finish there; check the outcome with mandate_status.

`MCR-401-004`

Approval signer does not own the wallet. This is answered on the person’s approval page, not to you. Tell them what it says and let them finish there; check the outcome with mandate_status.

`MCR-401-005`

Approval signature invalid. This is answered on the person’s approval page, not to you. Tell them what it says and let them finish there; check the outcome with mandate_status.

Limits

A limit was reached. Tell the person when it resets, using retry_after when it is set, and do not try again before then.

`KYC-429-002`

Daily verification attempts used. The person has used today’s identity-verification attempts. Tell them when it resets, from retry_after, and do not try before then.

`KYC-503-002`

Verification at daily capacity. Sumvin has reached today’s identity-verification capacity. Tell the person when it resets, from retry_after, and do not try before then.

Verification

The person has to verify something about themselves first, such as their phone number or their identity. Follow next when it is set; the guide explains each step.

`KYC-403-001`

Identity not verified yet. This needs the person’s identity verified. If they have already submitted, it is being reviewed; check their status rather than asking them to submit again. Next: call onboarding_status.

`KYC-403-002`

Identity verification not started. This needs the person’s identity verified, and they have not started. Hand them their verification link. Next: call kyc_start.

`KYC-403-004`

Phone number not verified. Identity verification needs a verified phone number first. kyc_start takes the person through both, phone first. Next: call kyc_start.

`KYC-403-005`

Identity verification declined. The reviewer decided not to verify this person, and that decision is final. Tell them, and point them to support if they believe it is wrong.

`KYC-503-001`

Verification not set up here. Identity verification is not configured in this environment. Nothing the person does will change that, so do not retry.

Permission

The credential behind this connection does not allow this. Do not retry with different arguments; the detail says what is missing and how the person can grant it.

`MCP-403-001`

Connection does not allow this. The person did not grant this connection the access this tool needs. The detail names it; the person grants it by reconnecting this app with that access. Use a tool the connection already covers meanwhile.

`MCP-403-002`

Tool not available on this connection. This connection does not serve that tool. Read the detail: it says whether the person needs an account first, or manages this in the Sumvin app.

`MCP-403-003`

Account cannot be served. The person’s account cannot be used for this right now. The detail says why; relay it, and point them to support if they think it is wrong.

`MCP-403-004`

No authorization for this action. Nothing authorizes this agent to take this action for the person. Do not retry; ask the person whether they want to approve it.

`MCR-403-001`

Mandate request belongs to someone else. That request was made to a different person. Do not act on it.

`PINT-403-001`

Approval does not cover this. The person’s approval for this agent does not include what this tool needs. Do not retry with other arguments; ask the person to approve the access the detail names.

`PINT-403-007`

Asks for more than its parent allows. This asks for more than the mandate it draws on authorises. Ask for less, or ask the person for a wider mandate.

`PINT-403-008`

Parent mandate no longer usable. The mandate this draws on has expired, been withdrawn or cannot be spent against. Read the person’s mandates before going further. Next: call pint_query.

`WAL-403-006`

Signing key cannot be primary. That wallet is the key the account signs with, and cannot also be its primary wallet. Choose another wallet.

Validation

The arguments were not accepted. Read the detail, correct the arguments it names, and call again. Ask the person when the right value is not yours to guess.

`BUD-400-003`

Budget period missing. A budget of this kind needs a period. Include one and call again.

`BUD-400-005`

Budget period too long. The period is longer than a budget allows. Shorten it and call again.

`CRD-400-001`

Card change not possible. The card cannot move to that state from the one it is in. The detail says why; read the card before trying something else.

`GEN-400-001`

Request not valid. The tool could not use what it was given. The detail says what to change.

`IPA-422-003`

Errand needs a spend limit. An errand needs a spend limit the person has agreed to. Ask them for one, then create the errand with it.

`MCP-422-001`

Invalid tool arguments. The arguments do not match the tool’s schema. The detail names each field and what is wrong with it; correct them and call again.

`MCP-422-002`

Tool arguments not accepted. The arguments were well formed but the tool could not use them, for example an unknown category. The detail lists what it accepts.

`MCR-400-002`

Approval signature unreadable. This is answered on the person’s approval page, not to you. Tell them what it says and let them finish there; check the outcome with mandate_status.

`MCR-422-001`

Mandate request not accepted. The request could not be turned into something the person can approve. The detail says which part; fix it with the person and ask again.

`MCR-422-002`

Mandate names the wrong wallet. The request names a wallet that cannot hold this mandate. Check the person’s wallets and ask with the right one. Next: call wallet_query.

`MCR-422-003`

Mandate network not supported. Mandates cannot be issued on that network. Ask with a supported one.

`PINT-422-003`

Mandate contradicts how it was signed. The mandate’s contents and the way it was signed disagree. Do not retry it; ask the person to approve a new request.

`PINT-422-004`

Mandate cannot be stated. Sumvin could not state what this mandate would authorise, for example because a limit or currency is missing. The detail says which; fix it and ask again.

`PINT-422-006`

Approval has expired. The approval this draws on has expired, so nothing can be issued under it. Ask the person whether they want to approve a new request. Next: call pint_query.

`UST-400-001`

Strategy needs a service connection. This strategy needs a service connection the person has not set up. They set it up in the Sumvin app first.

`WAL-400-001`

Not a wallet address that can be used. That address cannot be used here; only a wallet the person signs with directly can. Check the address with the person.

`WAL-400-004`

Primary network cannot change. The primary wallet’s network is fixed once set. Leave it as it is.

`WAL-400-005`

Network not supported for wallets. A smart wallet cannot be set up on that network. Use a supported one.

`WAL-400-006`

Nothing to update. The call named no change to make. Include the field you mean to change.

`WAL-400-007`

Primary wallet cannot be demoted. A primary wallet stops being primary only when another one is promoted. Promote the wallet the person wants instead.

Not found

Nothing by that name or identifier is visible to this connection. Check the identifier against a query tool’s results before trying again.

`BUD-404-001`

Budget not found. No budget with that identifier is visible here. List the person’s budgets to find the right one.

`CON-404-001`

Connection to a service not found. The service connection this needs is not set up for the person. They set it up in the Sumvin app.

`CRD-404-001`

Card not found. No card with that identifier is visible here. List the person’s cards to find the right one.

`IPA-404-001`

Errand not found. No errand with that identifier is visible to this connection. List the person’s errands to find the right one. Next: call errand_query.

`MCP-404-001`

Unknown tool. No tool has that name. Check it against tools/list, which returns everything this connection can call.

`MCP-404-002`

Unknown guide. No guide has that name. The detail lists the guides there are. Next: call sumvin_guide with {"name": "sumvin-sigil"}.

`MCP-404-003`

Unknown guide file. That guide has no file by that name. The detail lists its files; omit the file to load the guide itself. Next: call sumvin_guide with {"name": "sumvin-sigil"}.

`MCR-404-001`

Mandate request not found. No mandate request with that identifier is visible to this connection. Read the person’s requests to find the right one. Next: call mandate_status.

`PINT-404-001`

Mandate not found. No mandate with that identifier is visible to this connection. List the person’s mandates to find the right one. Next: call pint_query.

`RUL-404-001`

Rule not found. No rule with that identifier is visible here. List the person’s rules to find the right one.

`RUN-404-001`

Strategy run not found. No run with that identifier is visible here. List the strategy’s runs to find the right one.

`STR-404-001`

Strategy not found. No strategy with that identifier is visible here. List the strategies to find the right one.

`WAL-404-001`

Wallet not found. No wallet with that identifier is visible to this connection, or the account has no smart wallet yet. List the person’s wallets to check. Next: call wallet_query.

Conflict

The thing you are acting on is not in a state that allows this. Read its current state with the matching query tool, then decide with the person what to do; sending the same call again will not help.

`MCP-409-001`

Not ready for this action. What you are acting on is not waiting for this action right now. Read its current state before deciding with the person what to do. Next: call errand_query.

`MCP-409-002`

Cannot be cancelled now. It has gone too far to cancel. Read its current state and tell the person what that means for them.

`MCR-409-001`

Mandate request already answered. The person has already answered this request. Read what they decided. Next: call mandate_status.

`MCR-409-002`

Mandate no longer available. The mandate behind this request can no longer be issued. Read the request’s state and talk to the person about what they want. Next: call mandate_status.

`MCR-409-003`

Too many open mandate requests. The person already has as many requests waiting as are allowed. Read them, and let the person answer one before you ask for another. Next: call mandate_status.

`MCR-410-001`

Mandate request expired. The person did not answer in time, so the request lapsed. Ask them whether they still want it before you request it again.

`PINT-409-002`

Mandate already withdrawn. That mandate was already withdrawn, so there is nothing more to do to it. Next: call pint_query.

`PINT-409-009`

Mandate already finished. That mandate has already been spent or has expired, so it carries no authority left to withdraw and nothing was changed. Tell the person it is already finished rather than trying again. Next: call pint_query.

`STR-409-001`

Strategy already on. The person already has this strategy. There is nothing more to do.

`USR-424-002`

Account setup not finished. The person’s account has no active signing key yet, so it cannot act. Check where their setup stands. Next: call onboarding_status.

`UST-409-001`

Strategy not active yet. The strategy is still being switched on. Read it again shortly.

Server

Something failed on Sumvin’s side and retrying is not expected to help. Tell the person, and quote the code and trace_id if they contact support.

`MCP-500-001`

Tool call failed. The tool failed for a reason it cannot share. Do not retry it in a loop; tell the person, and quote the code and trace id if they contact support.

`MCP-500-002`

Unrecognised refusal. The tool refused with a reason this connection could not classify. The detail is what the tool said; tell the person, and quote the code and trace id if they contact support.

`MCP-503-001`

Connector not set up here. The connector is not configured in this environment. Nothing you or the person can change will fix it, so do not retry.

`MCR-500-001`

Approval checking misconfigured. Sumvin cannot check approvals because a setting is wrong. Nothing the person does will fix it; tell them.

`MCR-503-001`

Mandates not set up here. The approval page is not configured in this environment, so no mandate can be requested. Do not retry.

`SYS-503-002`

Service not configured. Sumvin could not authorize this request because the service is misconfigured. No argument change will help; tell the person.

​Reading a code

​What an error looks like

​Refused before the tool runs

​Retryable

​KYC-429-003-R

​KYC-503-003-R

​MCP-429-001-R

​MCP-429-002-R

​MCP-503-002-R

​MCP-503-003-R

​MCR-503-002-R

​UST-503-001-R

​WAL-409-002-R

​WAL-409-003-R

​Auth

​MCP-401-001

​MCR-401-001

​MCR-401-002

​MCR-401-003

​MCR-401-004

​MCR-401-005

​Limits

​KYC-429-002

​KYC-503-002

​Verification

​KYC-403-001

​KYC-403-002

​KYC-403-004

​KYC-403-005

​KYC-503-001

​Permission

​MCP-403-001

​MCP-403-002

​MCP-403-003

​MCP-403-004

​MCR-403-001

​PINT-403-001

​PINT-403-007

​PINT-403-008

​WAL-403-006

​Validation

​BUD-400-003

​BUD-400-005

​CRD-400-001

​GEN-400-001

​IPA-422-003

​MCP-422-001

​MCP-422-002

​MCR-400-002

​MCR-422-001

​MCR-422-002

​MCR-422-003

​PINT-422-003

​PINT-422-004

​PINT-422-006

​UST-400-001

​WAL-400-001

​WAL-400-004

​WAL-400-005

​WAL-400-006

​WAL-400-007

​Not found

​BUD-404-001

​CON-404-001

​CRD-404-001

​IPA-404-001

​MCP-404-001

​MCP-404-002

​MCP-404-003

​MCR-404-001

​PINT-404-001

​RUL-404-001

​RUN-404-001

​STR-404-001

​WAL-404-001

​Conflict

​MCP-409-001

​MCP-409-002

​MCR-409-001

​MCR-409-002