Errors - Archyon

Errors are returned with an appropriate HTTP status and a JSON body in a single, consistent shape:

{
  "error": "Human-readable message.",
  "code": "machine_readable_tag"
}

The error field is suitable for display to end users. The code field is populated only when callers are expected to programmatically branch on the failure mode (for example, to render a “Connect Notion” call-to-action when a Notion endpoint reports a missing integration). Generic validation errors omit code.

Status codes

Status	Meaning
`200 OK`	Request succeeded.
`201 Created`	Resource created. The response body contains the new resource.
`204 No Content`	Successful preflight (CORS) only.
`302 Found`	OAuth callback redirect. Only returned by `GET /api/auth/notion/callback`.
`400 Bad Request`	Validation failed, or the request requires organization context the caller does not have.
`401 Unauthorized`	The `Authorization` header is missing, malformed, or references a revoked credential.
`403 Forbidden`	The credential is valid but the role attached to it is insufficient for the operation.
`404 Not Found`	The resource does not exist, or is not visible to the caller. Some endpoints return `404` instead of `403` to avoid disclosing existence.
`409 Conflict`	The operation conflicts with current state — typically a duplicate identifier on create, or a referenced role on delete.
`502 Bad Gateway`	An upstream service (currently only Notion) returned an unexpected error.
`503 Service Unavailable`	A feature is not configured for the caller’s organization (currently only the Notion integration).
`500 Internal Server Error`	Unhandled exception. Includes a request identifier in the response body for support follow-up.

Hiding existence with 404

For workspaces and API tokens, attempting to operate on a resource the caller cannot read returns 404 Not Found instead of 403 Forbidden. This prevents enumeration attacks that could otherwise reveal whether a particular ID is in use.

Error codes

The following code values are a stable contract. Document any new codes here in the same pull request that introduces them.

`no_active_org`

The session has no Clerk organization context, and the requested endpoint operates on organization-scoped data.

{
  "error": "Active organization required to create or modify org-scoped entities.",
  "code": "no_active_org"
}

Resolution. In browsers, prompt the user to pick an organization in the Clerk switcher. In headless clients, re-mint the personal access token from a session that has the desired organization active. See Authentication › Organization binding.

`notion_misconfigured`

The caller’s organization has not connected a Notion workspace.

{
  "error": "Notion integration is not configured for this organization",
  "code": "notion_misconfigured"
}

Resolution. An organization administrator must complete the OAuth flow at Admin → Notion in the application. Clients should treat this as recoverable and direct the user to that surface.

`notion_access_denied`

Notion rejected an API request, typically because the integration was uninstalled from the workspace or the requested page was not shared with it.

{
  "error": "Notion rejected the request — re-connect Notion or check the integration's page access.",
  "code": "notion_access_denied"
}

Resolution. Re-run the Notion OAuth flow and verify the integration has been added to the relevant pages within Notion’s sharing UI.

`notion_not_found`

Notion returned 404 for a specific page or database ID. The integration is otherwise healthy.

{
  "error": "Notion couldn't find that page or database. Has it been shared with the integration?",
  "code": "notion_not_found"
}

Resolution. Confirm the page is shared with the Archyon integration in Notion. Pages must be explicitly added — Notion does not grant the integration access to all pages by default.

`bad_notion_url`

A submitted URL did not parse as a Notion page or database link.

{
  "error": "Couldn't find a Notion page or database ID in that URL",
  "code": "bad_notion_url"
}

Resolution. Verify the URL matches the format https://notion.so/… and contains a 32-character hexadecimal identifier.

`role_in_use`

A stakeholder role cannot be deleted because existing stakeholder links still reference it. The response includes the count of dependent links.

{
  "error": "Cannot delete \"Owner\" — 3 stakeholder link(s) still use this role. Reassign or remove them first.",
  "code": "role_in_use",
  "count": 3
}

Resolution. Reassign affected stakeholder links to a different role, or delete them, then retry the role deletion. The dependent link IDs can be obtained by listing stakeholders on the affected workspaces.

Branching on codes

Production clients should branch on code rather than the error string, which is subject to wording changes. A typical pattern:

async function archyonFetch(path: string, init?: RequestInit) {
  const res = await fetch(`https://archyon.app${path}`, init);
  if (res.ok) return res.json();

  const body = await res.json().catch(() => ({}));
  switch (body.code) {
    case "no_active_org":
      throw new NeedsOrgContextError(body.error);
    case "notion_misconfigured":
      throw new NeedsNotionSetupError(body.error);
    case "role_in_use":
      throw new RoleInUseError(body.error, body.count);
    default:
      throw new ArchyonApiError(res.status, body.error ?? res.statusText);
  }
}

Treat any future code value not listed above as an unknown error and surface the human-readable error message until your client adds explicit handling.

​Status codes

​Hiding existence with 404

​Error codes

​no_active_org

​notion_misconfigured

​notion_access_denied

​notion_not_found

​bad_notion_url

​role_in_use

​Branching on codes