Error codes
Every error code the API and the MCP server return, with its HTTP status.
API errors
Body: {"error": "CODE", "message": "…"}. Match on the code; the message is for people and may change.
| Status | Code | Meaning |
|---|---|---|
| 400 | INVALID_REQUEST | The body or parameters failed validation |
| 400 | TENANT_REQUIRED | The x-aspian-tenant header is missing or not a UUID |
| 400 | LOGIN_EXPIRED, SSO_FAILED | Single sign-on did not complete |
| 400 | REGISTRATION_INVALID, INVALID_ASSERTION | A passkey registration or assertion was malformed |
| 401 | UNAUTHENTICATED | Not signed in |
| 403 | BAD_ORIGIN | A state-changing request came from another origin |
| 403 | NOT_A_MEMBER, FORBIDDEN | You are not a member, or your role cannot do this |
| 403 | EMAIL_NOT_VERIFIED, NO_ACCOUNT | The account cannot sign in yet |
| 403 | PLAN_REQUIRES_APPROVAL | The plan needs an approval before it can apply |
| 403 | REQUESTER_CANNOT_APPROVE, NOT_AN_APPROVER | This person may not approve this plan |
| 403 | ASSERTION_INVALID | The passkey signature did not verify |
| 403 | NOT_AN_OPERATOR, NO_GRANT, RUNBOOK_NOT_IN_GRANT, RUNBOOK_NOT_PERMITTED | The operator’s grant does not cover this |
| 403 | SESSION_NOT_USABLE, NOT_YOUR_REQUEST | The agent session or approval request belongs to someone else |
| 404 | NOT_FOUND | The plan, organisation, request, link, incident or add-on does not exist |
| 404 | SSO_NOT_CONFIGURED, RUNBOOK_UNKNOWN | Not set up for this organisation |
| 409 | PLAN_CHANGED | The plan changed after the approval was requested |
| 409 | ALREADY_APPROVED, APPROVAL_NOT_NEEDED | Nothing more to approve |
| 409 | NO_APPROVERS, NO_PASSKEY | Nobody can approve yet: add a named approver with a passkey |
| 409 | PLAN_NOT_PENDING, PLAN_NOT_APPLICABLE, PLAN_CONFLICT, ILLEGAL_TRANSITION | The plan is not in a state that allows this |
| 410 | CHALLENGE_USED_OR_EXPIRED, LINK_USED, PLAN_EXPIRED | Single-use or time-limited, and already used or expired |
| 422 | REQUESTER_CANNOT_APPROVE, NOT_AN_APPROVER | When creating an approval request: this person cannot be asked |
| 422 | UNKNOWN_PARTNER | A partner attestation came from an unknown partner |
| 500 | PLAN_INTEGRITY | The stored plan no longer matches its hash. Nothing was applied |
| 500 | INTERNAL | Something went wrong and has been logged |
MCP errors
Tool results with isError: true and {"error": {"status", "code", "message"}}. Transport errors are JSON-RPC errors with the same code in data.
| Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHENTICATED, SESSION_INVALID | Bad agent key or session handle |
| 403 | KEY_PAUSED | The key was paused after three refused or failed applies |
| 403 | SCOPE_EXCEEDED, NOT_AUTHORISED | Outside the key’s projects or maximum risk class |
| 403 | SESSION_TAINTED, PLAN_REQUIRES_APPROVAL | Taint or risk means a person must approve |
| 403 | PLAN_NOT_OWNED, PLAN_EXPIRED | Not this key’s plan, or too old |
| 400 | PLAN_INVALID | The changes are malformed or cannot be combined |
| 400 | SECRET_VALUE_REFUSED | A value looked like a secret. Use a secret handle |
| 404 | PLAN_NOT_FOUND, KEY_NOT_FOUND | Does not exist |
| 409 | PLAN_STATE_CONFLICT, KEY_NOT_PAUSED | Wrong state for this action |
| 429 | RATE_LIMITED | More than 20 plans in an hour from this key |
| 502 | APPLY_FAILED | The cell refused or failed the change |
| 500 | INTERNAL | Something went wrong and has been logged |