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."
]
}
}
| Field | Is | Present |
|---|---|---|
code | One of the codes below | always |
message | What is wrong, in a sentence | always |
actions | Things the caller can do about it. Not exhaustive | with a refusal of an operation; an error of the service itself may have none |
rule | The rule that refused the change | with rule_violation |
blocking | The items in the way: kind, id, title, status | with some rules |
blocking_total | How many items are in the way in all | when blocking is cut |
current | The item as it is now, in short: what a list says of it. get has the description, the timeline and the history | with 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
| Code | HTTP status | When |
|---|---|---|
invalid_input | 400 | The 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_found | 404 | No item matches the ID or name that was given, there is no such link, no such operation, or nothing is served at that address. |
| 401 | The 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. | |
forbidden | 403 | The caller may not do this: an operation for admins, a permanent delete, or a request one of the guards turns away. |
version_conflict | 409 | The item changed since the caller read it. The error carries the item as it is now, in short, under current. |
rule_violation | 409 | The 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_exceeded | 413 | The 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_requests | 429 | Either 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. |
internal | 500 | Something 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:
| Rule | The change is refused when |
|---|---|
active_contents | A 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_deleted | delete is called on an item that is already deleted. restore brings it back. |
assigned_to_other | A task is being started by someone it is not assigned to. Change its assigned to link explicitly before taking it over. |
built_in | delete is called on one of the three users every instance starts with. |
completed_before_created | override_timestamp would put a task's completion before its creation. |
completed_before_earlier_completion | override_timestamp would put a completion before an earlier completion of the same task, which was reopened since. |
completed_container | Work is being put inside a task that is done, directly or through another group. Reopen the completed container first. |
contains_deleted_tasks | A project is being deleted for good while deleted tasks are still in it. They could be restored into no project. |
contains_tasks | A project is being deleted while it still contains tasks. |
created_after_change | override_timestamp would put the creation after a later change of status. |
created_after_recorded | override_timestamp would put the creation after the moment the item was recorded here. What is carried over happened before that. |
deleted | A change is made to an item that is deleted. Restore it first. |
has_assigned_tasks | A user is being deleted while tasks are still assigned to it. |
loop | A "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_completed | override_timestamp is asked to set the completion date of something that has none: a task that is not done, or a project. |
not_deleted | restore is called on an item that is not deleted. |
prefix_taken | A project is being created with a prefix another project has, or had: a prefix is never given twice. |
same_status | A 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_link | An item is being linked to itself. |
status_move_not_allowed | The move is not in the table of moves. The refusal lists where the task can go from where it is. |
timestamp_in_future | override_timestamp is given a moment that has not come yet. |
unfinished_contents | A task is being marked done while it contains unfinished tasks, at any depth. |
unfinished_dependencies | A task is being started or marked done while something it depends on is not finished. |
username_taken | A 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, withgetwhen it may be the description, then call again with the new version if the change still makes sense.rule_violation: follow one of theactions. 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, withgetandhistory, 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 error | What was changed |
|---|---|
invalid_input, not_found, forbidden, version_conflict, rule_violation, limit_exceeded | Nothing. The call was refused before anything was stored. |
unauthorized | Nothing. 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:
| Code | Means | Exit |
|---|---|---|
usage | The command was not typed as it is to be: an option it does not have, a word too many, no config given | 1 |
not_running | No service of this config is running. Nothing was sent to anyone | 1 |
not_this_service | Something answers at the config's address, and it is not the service of this config. Nothing was sent to it | 1 |
no_answer | The service took the connection and its answer did not come. A change may or may not have been stored | 2 |
cannot_start | serve 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 start | 1 |
config_invalid | The config file does not pass the check. The actions list each thing that is wrong | 1 |
config_busy | Another change to the config file is under way. Nothing was changed | 1 |
failed | Anything 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 stands | 1 |
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.