Errors use the same envelope as successes, with success: false:

{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to do that",
    "details": { }
  }
}

code is a string when Shellius has a specific reason to give you, and otherwise the numeric HTTP status. details is present only on some errors. Branch on code and the HTTP status; treat message as text for a person.

Status codes

Status	Meaning
200, 201	Success. 201 when something was created.
204	Success with no body, such as sign-out.
400	The request failed validation. message lists each problem.
401	No token, an expired or invalid token, or a revoked session.
403	Signed in, but not allowed.
404	No such resource in your organisation. Another tenant's ID looks the same as a missing one.
409	A conflict, most often a unique value that already exists.
429	Rate limited. See Pagination and rate limits.
500	A bug. Please report it.

Codes worth handling

Code	Status	What to do
INVALID_CREDENTIALS	401	Wrong email or password.
ACCOUNT_LOCKED	—	Too many failed sign-ins. Wait before retrying.
ACCOUNT_DISABLED	—	The user has been deactivated.
SESSION_REVOKED	401	The token predates a sign-out-everywhere, or the user is no longer active. Sign in again; refreshing will not help.
SSO_REQUIRED	403	The organisation requires single sign-on, so password sign-in is refused.
MFA_INVALID	401	The second-factor code was wrong.
MFA_CHALLENGE_EXPIRED	401	The mfaToken expired. Start again from login.
MFA_TOO_MANY_ATTEMPTS	429	Too many codes tried or requested.
PERMISSION_DENIED	403	The user's role lacks the permission key the endpoint needs.
ROLE_ESCALATION	—	You tried to grant, edit or assign a role with permissions you do not hold yourself.
PROD_HOST_REQUIRES_APPROVAL	—	The target is a production server and this path would have skipped review. Use an access request.
VALIDATION_ERROR	400	The body or query failed validation.
LINK_EXPIRED	—	An invite, reset or approval link is past its lifetime.

Dashes mark codes whose HTTP status varies by endpoint — branch on the code.

Not an exhaustive list

Shellius defines more codes than these, mostly specific to one feature — key import (KEY_UNSUPPORTED_FORMAT, KEY_PASSPHRASE_REQUIRED), break-glass, Quick Connect target checks. Log any code you do not recognise rather than failing on it.

Validation errors

Request bodies are validated strictly, and unknown fields are dropped rather than rejected. A 400 lists every problem at once, so you can fix them in one pass rather than one request at a time.