Errors - abadge

All abadge API errors share a consistent JSON envelope.

{
  "code": "ITEM_NOT_FOUND",
  "message": "Item not found.",
  "hint": "Verify the item ID and that it belongs to your organization.",
  "meta": {}
}

Validation errors include an extra issues array:

{
  "code": "VALIDATION_ERROR",
  "message": "Missing required field.",
  "hint": "Check the invalid input fields and try again.",
  "issues": [
    { "path": ["itemId"], "message": "Required" }
  ]
}

Error codes

Code	HTTP	Description
`BAD_REQUEST`	400	Generic bad request
`VALIDATION_ERROR`	400	Input failed schema validation; see `issues` array
`FIELD_NOT_FOUND`	400	Requested field does not exist on this item; `meta.availableFields` lists valid names
`MULTI_FIELD_ITEM`	400	Item has multiple fields; specify `field` to select one; `meta.availableFields` lists them
`STALE_VERSION`	400	Optimistic-concurrency conflict on item update; re-fetch and retry
`PUBLIC_KEY_REQUIRED`	400	`public_key_session` agent created without `publicKey` or `issueBootstrapToken`
`ENROLLMENT_REQUIRED`	400	Agent has no enrolled public key; run the enrollment flow first
`INVALID_BOOTSTRAP_TOKEN`	400	Bootstrap token is malformed or does not match any agent
`BOOTSTRAP_TOKEN_EXPIRED`	400	Bootstrap token has passed its 10-minute TTL
`INVALID_CAPABILITY`	400	Requested capability is not a valid enum value
`INVALID_CAPABILITY_LOCALITY`	400	Capability is not allowed for this agent locality (e.g. remote agent + `use`)
`INVALID_CAPABILITY_STORAGE`	400	Capability is not compatible with the item’s storage mode
`ORG_HEADER_REQUIRED`	400	User belongs to 2+ orgs; set `X-Abadge-Org-Id`. `meta.availableOrgIds` lists the user’s orgs
`ROTATE_KEY_INCOMPLETE`	400	Profile rotateKey payload does not rewrap every ZK item; `meta.missingItemIds` lists the omitted ones
`CONFIRMATION_MISMATCH`	400	`DELETE /v1/orgs/{orgId}` confirmation text does not match the org’s current name
`REAUTH_PASSWORD_REQUIRED`	400	`DELETE /v1/orgs/{orgId}` re-authentication requested but the account has no password set (social-login only); set one via password reset first
`INVALID_CLAIM_TOKEN`	400	auth.md claim token is unknown, already used, or malformed
`CLAIM_TOKEN_EXPIRED`	400	auth.md claim token passed its 24-hour TTL; register again
`OTP_NOT_REQUESTED`	400	`claim/complete` called before `claim` issued an OTP
`OTP_INVALID`	400	Supplied auth.md claim OTP is incorrect
`OTP_EXPIRED`	400	auth.md claim OTP passed its 10-minute TTL; restart the claim
`OTP_ATTEMPTS_EXCEEDED`	400	Too many wrong OTP attempts (max 5); restart the claim
`UNAUTHORIZED`	401	No valid bearer credential provided
`REAUTH_FAILED`	401	`DELETE /v1/orgs/{orgId}` re-authentication failed: the supplied account password is incorrect
`NO_ORG_MEMBERSHIP`	401	Authenticated user has no organization membership; complete onboarding
`ORG_MEMBERSHIP_REQUIRED`	401	`X-Abadge-Org-Id` refers to an organization the user is not a member of
`AGENT_NOT_ENROLLED`	401	Agent credential present but public key not enrolled
`AGENT_SESSION_NOT_FOUND`	401	`abs_...` session token not found or already expired
`AGENT_CHALLENGE_NOT_FOUND`	401	Challenge ID not found or already used
`AGENT_CHALLENGE_EXPIRED`	401	Challenge has passed its 60-second TTL
`SESSION_REFRESH_FAILED`	401	SDK-only: `AbadgeAgentClient` background session refresh exhausted retries; call `disconnect()` and `connect()` again
`FORBIDDEN`	403	Authenticated but not authorized for this operation
`PERMISSION_DENIED`	403	No matching permission for (agent, item, capability)
`PERMISSION_EXPIRED`	403	Permission exists but has passed its `expiresAt`
`AGENT_REVOKED`	403	Agent has been revoked and cannot authenticate
`MEMBER_INSUFFICIENT_ROLE`	403	Operation requires a higher org role
`MEMBER_AGENT_OWNERSHIP`	403	Agent does not belong to the requesting org member
`NOT_FOUND`	404	Generic not found
`ITEM_NOT_FOUND`	404	Item ID does not exist, is deleted, or belongs to another user
`AGENT_NOT_FOUND`	404	Agent ID does not exist or belongs to another user
`PERMISSION_NOT_FOUND`	404	Permission ID does not exist
`PROFILE_NOT_FOUND`	404	Profile ID does not exist or belongs to another org
`VAULT_NOT_FOUND`	404	Vault has not been bootstrapped yet
`INVITE_NOT_FOUND`	404	Invite token does not exist
`INVITE_EXPIRED`	404	Invite token passed its expiry
`MOUNT_NOT_FOUND`	404	Mount handle does not exist or was already redeemed (one-shot)
`AGENT_ALREADY_ENROLLED`	409	Agent already has a public key enrolled
`CONFLICT`	409	Generic conflict
`VAULT_ALREADY_EXISTS`	409	Vault bootstrap attempted when vault already exists
`PROFILE_ALREADY_EXISTS`	409	Profile with this name already exists in the org
`PROFILE_LIMIT_EXCEEDED`	409	Personal accounts are limited to a single profile; `profiles.create` rejects an additional profile on a personal org
`PROFILE_NOT_EMPTY`	409	Profile deletion blocked because it still contains items
`ITEM_DELETED`	409	Operation attempted on a soft-deleted item
`ITEM_ALREADY_EXISTS`	409	An item with this ID already exists; generate a new UUID and retry
`SLUG_TAKEN`	409	Organization slug is already in use
`INVITE_ALREADY_USED`	409	Invite token has already been accepted
`ALREADY_MEMBER`	409	User is already a member of the organization
`CLAIM_EMAIL_IN_USE`	409	auth.md claim email already maps to an existing account
`CLAIM_ALREADY_COMPLETED`	409	auth.md claim was already completed
`PERMISSION_ALREADY_EXISTS`	409	One or more capabilities in a `permissions.create` batch are already granted on this `(agent, item)` pair; `meta.duplicateCapabilities` lists every duplicate. The batch is rejected atomically
`RATE_LIMITED`	429	Too many requests; back off and retry. Carries `meta.retryAfter`, `meta.limit`, `meta.resetAt` — see Rate limiting.
`INTEGRITY_ERROR`	500	Server-side data integrity failure
`SERVICE_UNAVAILABLE`	503	Database at capacity or briefly unreachable; retry after `meta.retryAfterSeconds`

SDK error handling

The SDK wraps every API error in AbadgeApiError:

import { AbadgeAgentClient, AbadgeApiError } from "@abadge/sdk";

const agent = new AbadgeAgentClient({ apiUrl, agentId, privateKey });
await agent.connect();

try {
  const result = await agent.access.read(itemId);
} catch (err) {
  if (err instanceof AbadgeApiError) {
    console.error(err.code);    // e.g. "PERMISSION_DENIED"
    console.error(err.message); // human-readable
    console.error(err.hint);    // remediation
    console.error(err.meta);    // structured (may be undefined)
    console.error(err.issues);  // VALIDATION_ERROR only
  }
}

When accessing multi-field items, inspect meta.availableFields to choose the right field:

try {
  await agent.access.read(itemId);
} catch (err) {
  if (err instanceof AbadgeApiError && err.code === "MULTI_FIELD_ITEM") {
    const fields = err.meta?.availableFields as string[];
    await agent.access.read(itemId, { field: fields[0] });
  }
}

See Field delivery for the full resolution model.