Error responses
401, 402, 403, 404, 409 and 426 — what each means, what it looks like, and what to do about it.
The API answers with a JSON body of {"error": "a sentence"}, and the sentence
is written for a person. Here are the statuses you will meet and what they mean.
401 — you are not signed in
not signed in: the session has expired or was ended — by a
password reset, for instance.
incorrect email or password on sign-in says only that much, deliberately.
current password is incorrect when changing a password.
For an agent, 401 unauthorized means a key that no longer works — after a
reset or a deletion — and
enrollment token is not valid means a token that has expired, been used or
been replaced (troubleshooting).
402 — the workspace is suspended
this workspace is suspended — subscribe to make changes again. Every write in
a suspended workspace; reads keep working. The
way out is to pay.
403 — your role is not enough
requires the operator role — the response names the role that would have been
enough (roles). You will not see it in the application,
because your role does not have the button that would raise it; you meet it
through the API. Two unusual ones:
a token cannot be given a role above your own and
a token has no name of its own to change.
404 — it is not there, or not for you
Anything a workspace does not permit answers 404: an unknown workspace, one
still being built, a deleted one, another workspace in the address, a job, agent
or account that does not exist (no such account, agent not found). Never
403 — that would be an admission that the thing exists. A credential presented
to the wrong workspace ends in a 401, because nobody there knows it.
409 — not right now
A conflict with a rule that has a page of its own elsewhere in this manual:
| Sentence | Where the rule is |
|---|---|
the pro plan allows 15 agents … | plans |
the pro plan allows 5 account(s), and this workspace already has that many | plans, invitations |
this account was turned off by a plan change … | the choice at a downgrade |
you cannot change your own role, you cannot block yourself, you cannot delete your own account | your own account |
this is the only administrator — promote someone else first | the last admin |
that address already has an account | invitations |
this account is already active — send a password reset instead | sending it again |
cannot run a disabled job, this job has no agent assigned to run it | running by hand |
426 — the agent needs a new version
unsupported protocol version, with a body naming the window:
{"error":"unsupported protocol version","expected":2,"min":1,"max":2}. The
agent speaks a protocol version outside the window Runjet serves and its jobs
have stopped; what to do about it is in
upgrading.
Two more worth mentioning
429 after ten attempts at signing in, registering or resetting within a minute
from one address — wait a minute. 503 scheduling is not running for this workspace on running by hand at a moment when the workspace's scheduler is not
up; it will go through in a moment.