Errors

The envelope

Every failed request answers with the same shape — an ordered array, because one request can produce more than one problem:

{
  "errors": [
    {
      "code": "SCOPE_MISSING",
      "message": "This key is missing the required scope: users:write.",
      "param": null,
      "meta": { "required_scope": "users:write" }
    }
  ]
}

• code is the stable, machine-readable contract. Branch on it. Codes are never renamed silently.

• message is human-readable and may change.

• param names the offending field on a validation error.

• meta carries structured extras (e.g. retry_after on a rate limit, required_scope on a scope error, an existing account's providers on ACCOUNT_EXISTS).

Internal (5xx) faults return an opaque INTERNAL message on purpose — a detailed server error is a classic accidental disclosure channel.

HTTP status codes

Handling errors in an SDK

The Node SDK throws AtlasApiError on any non-2xx, exposing status, the full errors array, and helpers:

import { AtlasApiError } from '@atlas/backend';

try {
  await atlas.organizations.memberships.update(orgId, userId, { role: 'org:member' });
} catch (e) {
  if (e instanceof AtlasApiError && e.hasCode('LAST_ADMIN')) {
    // Can't demote the last admin — pick another admin first.
  } else {
    throw e;
  }
}

Error code catalog

Request

VALIDATION_FAILED · NOT_FOUND · RATE_LIMITED · IDEMPOTENCY_CONFLICT · NOT_CONFIGURED · CONFLICT · INTERNAL

Authentication & authorization

UNAUTHENTICATED · INVALID_KEY · FORBIDDEN · SCOPE_MISSING

Identity & credentials

IDENTIFIER_EXISTS · IDENTIFIER_NOT_FOUND · VERIFICATION_EXPIRED · VERIFICATION_FAILED · TOO_MANY_ATTEMPTS · PASSWORD_BREACHED · PASSWORD_POLICY · PASSWORD_EXPIRED · LOCKED · BANNED · MFA_REQUIRED · MFA_ALREADY_ENROLLED · MFA_NOT_ENROLLED · STEP_UP_REQUIRED · LAST_EMAIL · SESSION_EXPIRED · TOKEN_REUSE_DETECTED

OAuth & linking

OAUTH_STATE_INVALID · PROVIDER_TOKEN_UNAVAILABLE · OAUTH_EXCHANGE_FAILED · LAST_AUTH_METHOD · IDENTITY_ALREADY_LINKED · ACCOUNT_EXISTS · WALLET_GATE_UNMET

Organizations

LAST_ADMIN · ALREADY_MEMBER · ROLE_IN_USE · MEMBERSHIP_LIMIT_REACHED · SSO_REQUIRED

Sign-up gating & bot defence

STRATEGY_DISABLED · SIGN_UP_RESTRICTED · WAITLISTED · IDENTIFIER_NOT_ALLOWED · DISPOSABLE_EMAIL_BLOCKED · SMS_REGION_BLOCKED · AUTHENTICATOR_NOT_ALLOWED · CAPTCHA_REQUIRED · CAPTCHA_FAILED · CHALLENGE_UNAVAILABLE

Kill switches, network & policy

READ_ONLY_MODE · SIGN_UPS_DISABLED · SIGN_INS_DISABLED · PROVIDER_DISABLED · PROVIDER_SIGN_UP_DISABLED · PROVIDER_SIGN_IN_DISABLED · IP_NOT_ALLOWED

Extensibility & risk

ACTION_BLOCKED (a fail-closed Action denied the flow) · HIGH_RISK_BLOCKED (adaptive MFA blocked a high-risk sign-in with no enrolled factor)