When a call fails
Every failure comes back as JSON with a message, never as an empty body and never as a stack trace. There are five statuses to know, and one distinction that matters more than all of them.
On this page(4 sections)
A refusal is a result
The daemon does not crash at you. A call it will not perform answers with a status and an object carrying a message, and where the reason is structured (a body that did not match its shape), the object carries the specific fields it could not accept.
curl -X POST "$SANDBOX/git/root/commit" \
-H "x-intentic-control: $INTENTIC_TOKEN" \
-H "content-type: application/json" \
-d '{}'
HTTP/1.1 400 Bad Request
content-type: application/json
{ "message": "Input validation failed",
"issues": [ { "path": ["message"], "message": "Required" } ] }The playground on every group page produces exactly this when you clear a required field, which is the cheapest way to see the shape without a sandbox in front of you.
Every status, and what it means
| Status | Means |
|---|---|
400 | The input did not match the declared shape, or a path escaped the workspace. |
401 | No credential, or one that does not verify. The two are indistinguishable on purpose: telling them apart would confirm which half of a guess was right. |
403 | A real credential that may not go there: an identity that is not a member, a member below the route's role floor (the answer names the tier), or a control token outside its scope. |
404 | No such route on this daemon, or no such thing. Also the answer for the daemon's own credential files, which are not readable through the file routes at all. |
409 | The state will not allow it right now, and waiting might. Landing a conversation's work while its turn is running, restoring files an agent is editing, starting a second loop on one conversation. |
413 | Too large. The file routes are bounded so that one enormous log cannot stall the daemon for everyone. |
Reported, not raised
A whole class of things that look like failures are answers instead, and this is the single most useful thing to know about reading this API. A push with no remote configured, a pull that cannot fast-forward, a merge that conflicts, a country switch that did not take: none of those raise. They come back 200 with an object that says what happened.
The rule behind it is that these are ordinary outcomes a screen has to render, not breakages. If a person would look at the result and decide something, it is a value. If the request itself was wrong, it is a status.
What is worth retrying
409 is the only one where the same request may succeed later without anything else changing, and even then only once the turn or operation that is holding the state has finished. 400, 403 and 413 will answer the same way for ever. 401 is worth exactly one retry, after renewing the session.
404 deserves a second look before you retry it: on an older daemon it may mean the route does not exist yet rather than that the thing does not. Old daemon, new client is how to tell those apart.