Vigile
SearchContents

Documentation

Errors and refusals

A call that cannot be carried out is answered with what is wrong and, where there is a next step, what it is. The answer has one shape, over MCP, over HTTP and on the command line.

The shape of an error

{
  "error": {
    "code": "rule_violation",
    "message": "Task WEB-003 cannot be started: it is waiting for a dependency to finish.",
    "rule": "unfinished_dependencies",
    "blocking": [
      { "kind": "task", "id": "WEB-002", "title": "Cart page lists the items and the total", "status": "open" }
    ],
    "actions": [
      "Finish or cancel the items it depends on.",
      "Or call remove_link with type \"depends on\" if the dependency no longer applies.",
      "Or call list_next_tasks to pick work that can start now."
    ]
  }
}
FieldIsPresent
codeOne of the codes belowalways
messageWhat is wrong, in a sentencealways
actionsThings the caller can do about it. Not exhaustivewith a refusal of an operation; an error of the service itself may have none
ruleThe rule that refused the changewith rule_violation
blockingThe items in the way: kind, id, title, statuswith some rules
blocking_totalHow many items are in the way in allwhen blocking is cut
currentThe item as it is now, in short: what a list says of it. get has the description, the timeline and the historywith version_conflict

Where it arrives:

  • HTTP: as the body, with the status of the code.
  • MCP: as the text of a tool result that is marked as an error.
  • Command line: printed in words, with the items in the way and the actions; with --json, as this JSON on the error output.

Codes

CodeHTTP statusWhen
invalid_input400The input is not what the operation takes: a value of the wrong type, a required field that is missing, a field it does not know, text that is too long, an ID that matches more than one item, a body that is not JSON, a request other than a POST that brings a body. The message names the field.
not_found404No item matches the ID or name that was given, there is no such link, no such operation, or nothing is served at that address.
unauthorized401The connection may not act as anyone: it has no key where one is required, the key is not valid, or the key's user no longer exists.
forbidden403The caller may not do this: an operation for admins, a permanent delete, or a request one of the guards turns away.
version_conflict409The item changed since the caller read it. The error carries the item as it is now, in short, under current.
rule_violation409The change would break a rule of the plan. The error carries the rule and what to do under actions, and with some rules the items in the way under blocking.
limit_exceeded413The request is too large: a body of more than 1 MB, or a change that touches more records than can be stored in one step.
too_many_requests429Either too many clients are listening to the stream of changes, in all, from one address or from the service's own machine, or a read by get or list_history was overtaken repeatedly by changes to the plan. Close stream clients in the first case; read again in the second.
internal500Something went wrong inside the service that was nobody's mistake. The service's log says what. It is the one code after which a change may have been stored: the message says what stands, or that the change was not confirmed.

In the service's log, a refused call has its line like any other, with the code as its result and the rule when there is one:

2026-01-12T09:14:03.120Z op=set_task_status caller=agent1 kind=write ms=0.6 result=rule_violation rule=unfinished_dependencies

Rules

A rule_violation names the rule. These are all of them:

RuleThe change is refused when
active_contentsA task is being cancelled while it contains tasks that are in progress or in review, at any depth. Finish them or move them out first.
already_deleteddelete is called on an item that is already deleted. restore brings it back.
assigned_to_otherA task is being started by someone it is not assigned to. Change its assigned to link explicitly before taking it over.
built_indelete is called on one of the three users every instance starts with.
completed_before_createdoverride_timestamp would put a task's completion before its creation.
completed_before_earlier_completionoverride_timestamp would put a completion before an earlier completion of the same task, which was reopened since.
completed_containerWork is being put inside a task that is done, directly or through another group. Reopen the completed container first.
contains_deleted_tasksA project is being deleted for good while deleted tasks are still in it. They could be restored into no project.
contains_tasksA project is being deleted while it still contains tasks.
created_after_changeoverride_timestamp would put the creation after a later change of status.
created_after_recordedoverride_timestamp would put the creation after the moment the item was recorded here. What is carried over happened before that.
deletedA change is made to an item that is deleted. Restore it first.
has_assigned_tasksA user is being deleted while tasks are still assigned to it.
loopA "contains" or "depends on" link would close a loop, so that none of the items on it could ever finish. The refusal shows the path.
not_completedoverride_timestamp is asked to set the completion date of something that has none: a task that is not done, or a project.
not_deletedrestore is called on an item that is not deleted.
prefix_takenA project is being created with a prefix another project has, or had: a prefix is never given twice.
same_statusA task or project is being moved to the status it already has. For in_progress the refusal says whether the task is assigned to the caller, to other users or to nobody.
self_linkAn item is being linked to itself.
status_move_not_allowedThe move is not in the table of moves. The refusal lists where the task can go from where it is.
timestamp_in_futureoverride_timestamp is given a moment that has not come yet.
unfinished_contentsA task is being marked done while it contains unfinished tasks, at any depth.
unfinished_dependenciesA task is being started or marked done while something it depends on is not finished.
username_takenA user is being created with a username that is in use, also by a deleted user.

What to do with a refusal

  • version_conflict: someone changed the item since it was read. The error holds the item as it is now, in short. Look at what changed, with get when it may be the description, then call again with the new version if the change still makes sense.
  • rule_violation: follow one of the actions. Repeating the same call will be refused again while the plan is as it is.
  • not_found, or an ID that matches more than one item: the error says how to name the item, for example by putting the kind in front.
  • unauthorized: send a key, or a valid one. An admin issues keys.
  • internal: something went wrong inside the service, and its log has the cause. Do not take it to mean that nothing was changed. Where a change was stored and a later step failed, the message says what stands and what to do, as in "User agent2 was created, but its API key could not be stored". Where the message says that the change was not confirmed, it is not known whether it was stored: read the item again, with get and history, before sending the change again.

After invalid_input, not_found, forbidden, version_conflict, rule_violation and limit_exceeded, nothing was changed: the call was refused before anything was stored. unauthorized is given before a call reaches an operation. The rows of those codes are what a service left behind when it gave each of them while this site was built:

The errorWhat was changed
invalid_input, not_found, forbidden, version_conflict, rule_violation, limit_exceededNothing. The call was refused before anything was stored.
unauthorizedNothing. The call was turned away before it reached an operation.
internal, with a message that says what stands, as in "User keyless was created, but its API key could not be stored, so it cannot connect yet."Part of it: what the message says stands, and it says what to do about the rest.
internal, "The service hit an unexpected error. The change was not confirmed."Not known. The same answer is given when the change was stored and when it was not. Look at the item, with get and its history, before sending the change again.

The command line's own codes

With --json, the command line reports its own failures in the same shape, under codes the service does not use:

CodeMeansExit
usageThe command was not typed as it is to be: an option it does not have, a word too many, no config given1
not_runningNo service of this config is running. Nothing was sent to anyone1
not_this_serviceSomething answers at the config's address, and it is not the service of this config. Nothing was sent to it1
no_answerThe service took the connection and its answer did not come. A change may or may not have been stored2
cannot_startserve could not start: the port is taken, another service holds the data folder, the config names a user that does not exist. What has happened to the data folder by then depends on the step that failed: see the steps of a start1
config_invalidThe config file does not pass the check. The actions list each thing that is wrong1
config_busyAnother change to the config file is under way. Nothing was changed1
failedAnything else that went wrong in the command itself. The message says what; where the command had written something, such as a setting, it says that it stands1

A refusal by the service keeps the service's code and ends with 1. An exit code of 1 does not by itself say that nothing was changed: see exit codes.