Error Codes Reference

Registry API Errors HTTP 4xx / 5xx

These codes appear in the error_code field of error responses from the REST API.

Code	HTTP	Name	Description
`1001`	400	`INVALID_RRN_FORMAT`	RRN does not match expected pattern
`1002`	400	`INVALID_TIER`	Verification tier value not recognized
`1003`	400	`TIER_SKIP_NOT_ALLOWED`	Cannot skip verification tiers
`1004`	400	`EVIDENCE_URL_REQUIRED`	`evidence_url` required for tier upgrade
`2001`	401	`AUTH_REQUIRED`	Bearer token required for write operations
`2002`	403	`AUTH_INVALID`	Bearer token invalid or expired
`3001`	404	`ROBOT_NOT_FOUND`	RRN not found in registry
`3002`	404	`NODE_NOT_FOUND`	No node registered for RRN prefix
`3003`	404	`DELEGATION_NOT_FOUND`	No delegation for namespace prefix
`4001`	429	`RATE_LIMITED`	Too many requests — see `Retry-After` header
`5001`	500	`INTERNAL_ERROR`	Registry internal error

Error response shape

{
  "success": false,
  "error_code": 3001,
  "error": "ROBOT_NOT_FOUND",
  "message": "RRN not found in registry",
  "rrn": "RRN-000000000042"   // included where applicable
}

Federation Errors §17

Returned by the distributed resolution layer when traversing the node trust chain. See §17 Federated Registry for full semantics.

Code	Name	Description
`6001`	`NODE_NOT_FOUND`	No node registered for RRN prefix
`6002`	`DELEGATION_INVALID`	Node delegation cert signature failed
`6003`	`RECORD_SIG_INVALID`	Robot record signature failed
`6004`	`SYNC_CONFLICT`	Sync conflict — root record wins
`6005`	`NODE_UNAVAILABLE`	Authoritative node unreachable
`6006`	`CACHE_STALE`	Cached record expired, live fetch failed

SDK Error Classes

TypeScript (`rcan-ts`)

All SDK errors extend RCANError, which itself extends Error. Errors carry a code string matching the names above.

RCANError — base class
- RCANValidationError — invalid input (e.g. malformed RRN)
- RCANGateError — confidence gate blocked action
  - gateType: string
  - value: number
  - threshold: number
- RCANNodeError — federation / node error
  - nodeUrl: string
  - RCANNodeNotFoundError
    - rrn: string
  - RCANNodeSyncError
    - cause: unknown
  - RCANNodeTrustError
    - reason: 'invalid_signature' | 'expired_cert' | 'unknown_issuer' | 'missing_pubkey'

Catching errors

import {
  RCANNodeNotFoundError,
  RCANNodeTrustError,
  RCANGateError,
} from 'rcan-ts';

try {
  const robot = await client.resolve('RRN-BD-000000000001');
} catch (err) {
  if (err instanceof RCANNodeNotFoundError) {
    console.error('RRN not found:', err.rrn);
  } else if (err instanceof RCANNodeTrustError) {
    console.error('Trust failure:', err.reason); // e.g. 'invalid_signature'
  } else if (err instanceof RCANGateError) {
    console.error(`Gate blocked: ${err.value} < ${err.threshold}`);
  }
}

Python (`rcan`)

from rcan.exceptions import (
    RCANError,           # base
    RCANValidationError, # invalid input
    RCANGateError,       # confidence gate blocked
    RCANNodeError,       # federation / node base
    RCANNodeNotFoundError,
    RCANNodeSyncError,
    RCANNodeTrustError,
)

try:
    robot = client.resolve("RRN-BD-000000000001")
except RCANNodeNotFoundError as e:
    print(f"RRN not found: {e.rrn}")
except RCANNodeTrustError as e:
    # e.reason: 'invalid_signature' | 'expired_cert' | ...
    print(f"Trust failure: {e.reason}")
except RCANGateError as e:
    print(f"Gate blocked: {e.value} < {e.threshold}")

← Docs index API Reference §17 Federated Registry