Error Codes

This page documents all error codes returned by the Beltic SDK. Error codes help you identify specific issues and implement appropriate error handling.

Error Code Format

Error codes follow a consistent format:

Prefix	Category
`RV-`	Runtime Validation (date checks, freshness)
`SIG-`	Signature operations
`TC-`	Trust Chain verification
`POL-`	Policy violations

Validation Errors (RV-*)

Date Order Errors

These errors indicate invalid date relationships in credentials.

Code	Description	Solution
`RV-D001`	`issuanceDate` must be before `expirationDate`	Ensure credential doesn’t expire before it’s issued
`RV-D002`	`lastUpdatedDate` must be between `issuanceDate` and `expirationDate`	Update date must fall within validity period
`RV-D003`	`proof.created` must be >= `issuanceDate`	Signature can’t be created before credential issuance

Example:

// This will trigger RV-D001
const credential = {
  issuanceDate: "2025-12-01T00:00:00Z",
  expirationDate: "2025-01-01T00:00:00Z",  // Before issuance!
};

Freshness Warnings

These warnings indicate stale verification data. They don’t prevent validation but should be addressed.

Code	Description	Threshold
`RV-F001`	Sanctions screening is stale	> 90 days
`RV-F002`	PEP assessment is stale	> 180 days
`RV-F003`	Adverse media assessment is stale	> 180 days
`RV-F004`	Tax verification is stale	> 730 days (2 years)
`RV-F005`	Credential expired	Past `expirationDate`

Example:

const result = validateDeveloperCredential(credential);
if (result.ok && result.warnings.length > 0) {
  for (const warning of result.warnings) {
    if (warning.code === 'RV-F001') {
      console.log('Consider re-screening for sanctions');
    }
  }
}

Data Category Errors

These errors indicate missing compliance requirements for sensitive data types.

Code	Description	Requirement
`RV-X001`	PHI data requires HIPAA certification	Add `hipaa` to `complianceCertifications`
`RV-X002`	Financial data requires PCI-DSS or SOC2	Add `pci_dss` or `soc2_type2` to `complianceCertifications`
`RV-X003`	Children’s data requires age restrictions	Set `ageRestrictions` to `13+` or higher

Example:

// This will trigger RV-X001
const credential = {
  dataCategoriesProcessed: ["phi"],  // Protected Health Information
  complianceCertifications: ["soc2_type2"],  // Missing HIPAA!
};

Signature Errors (SIG-*)

Parsing Errors

Code	Description	Solution
`SIG-001`	Invalid JWS structure	Ensure token has 3 base64url-encoded parts separated by dots
`SIG-002`	Unsupported algorithm	Use `EdDSA` or `ES256` only
`SIG-003`	Algorithm “none” not allowed	Always sign credentials with a real algorithm
`SIG-004`	Invalid header encoding	Header must be valid base64url-encoded JSON
`SIG-005`	Invalid payload encoding	Payload must be valid base64url-encoded JSON
`SIG-006`	Invalid signature encoding	Signature must be valid base64url

Key Resolution Errors

Code	Description	Solution
`SIG-007`	Key resolution failed	Ensure `keyResolver` returns a valid key for the given DID/kid

Verification Errors

Code	Description	Solution
`SIG-008`	Signature verification failed	Check that the correct public key is used
`SIG-009`	Token expired	`exp` claim is in the past
`SIG-010`	Token not yet valid	`nbf` claim is in the future
`SIG-011`	Issuer mismatch	`iss` claim doesn’t match `expectedIssuer`
`SIG-012`	Audience mismatch	`aud` claim doesn’t match `expectedAudience`
`SIG-013`	Missing required claim	Required JWT claim (iss, sub, jti, etc.) is missing
`SIG-014`	Schema validation failed	Credential in `vc` claim doesn’t match schema

Example:

try {
  await verifyCredential(token, options);
} catch (error) {
  if (error instanceof SignatureError) {
    switch (error.code) {
      case 'SIG-008':
        console.error('Wrong public key - check kid header');
        break;
      case 'SIG-009':
        console.error('Token expired - request new credential');
        break;
      case 'SIG-011':
        console.error('Unexpected issuer - verify trust');
        break;
    }
  }
}

Trust Chain Errors (TC-*)

Code	Description	Solution
`TC-001`	Agent credential verification failed	Check agent token signature and claims
`TC-002`	Developer credential fetch failed	Ensure `fetchDeveloperCredential` callback works
`TC-003`	Developer credential verification failed	Check developer token signature and claims
`TC-004`	Developer credential ID mismatch	Agent’s `developerCredentialId` doesn’t match fetched credential
`TC-005`	Status check failed	`checkStatus` callback encountered an error
`TC-006`	Agent credential revoked	Agent credential is no longer valid
`TC-007`	Developer credential revoked	Developer credential is no longer valid

Example:

try {
  await verifyAgentTrustChain(token, options);
} catch (error) {
  if (error instanceof TrustChainError) {
    console.log(`Failed at step: ${error.step}`);
    // AGENT_VERIFY, DEVELOPER_FETCH, DEVELOPER_VERIFY, STATUS_CHECK
    
    if (error.agentCredential) {
      console.log('Partial agent data:', error.agentCredential);
    }
  }
}

Policy Violation Errors (POL-*)

Code	Description
`POL-001`	KYB tier requirement not met
`POL-002`	Prompt injection score too low
`POL-003`	PII leakage score too low
`POL-004`	Tool abuse score too low
`POL-005`	Harm refusal score too low
`POL-006`	Verification level requirement not met
`POL-007`	Prohibited data category processed

Example:

try {
  await verifyAgentTrustChain(token, {
    policy: {
      minKybTier: 'tier_2',
      minPromptInjectionScore: 85,
    },
  });
} catch (error) {
  if (error instanceof PolicyViolationError) {
    for (const violation of error.violations) {
      console.log(`${violation.type}: required ${violation.required}, got ${violation.actual}`);
    }
    
    if (error.hasType('KYB_TIER')) {
      console.error('Developer needs higher KYB verification');
    }
  }
}

HTTP Signature Errors

Code	Description	Solution
`HTTP-001`	Missing Signature-Agent header	Add `Signature-Agent` header to request
`HTTP-002`	Missing Signature-Input header	Add `Signature-Input` header to request
`HTTP-003`	Missing Signature header	Add `Signature` header to request
`HTTP-004`	Invalid Signature-Input format	Check RFC 9421 format
`HTTP-005`	Key directory fetch failed	Ensure key directory URL is accessible
`HTTP-006`	Key not found in directory	Verify `keyid` matches a key in directory
`HTTP-007`	Signature verification failed	Check private/public key pair
`HTTP-008`	Signature expired	Request is too old, `expires` has passed
`HTTP-009`	Content-Digest mismatch	Request body was modified

Error Handling Best Practices

Categorize Errors

import {
  ValidationError,
  SignatureError,
  TrustChainError,
  PolicyViolationError,
} from '@beltic/sdk';

async function handleCredential(token: string) {
  try {
    return await verifyAgentTrustChain(token, options);
  } catch (error) {
    if (error instanceof ValidationError) {
      // Schema/format issues - likely caller error
      return { status: 400, error: 'Invalid credential format' };
    }
    
    if (error instanceof SignatureError) {
      // Cryptographic issues - could be tampering
      return { status: 401, error: 'Invalid signature' };
    }
    
    if (error instanceof TrustChainError) {
      // Trust chain broken - credential relationship issues
      return { status: 403, error: 'Trust chain verification failed' };
    }
    
    if (error instanceof PolicyViolationError) {
      // Policy issues - credential doesn't meet requirements
      return { status: 403, error: 'Policy requirements not met' };
    }
    
    // Unknown error
    throw error;
  }
}

Log Details, Return Safe Messages

import { getPublicMessage, sanitizeMessage } from '@beltic/sdk';

try {
  await verifyCredential(token, options);
} catch (error) {
  // Log full details for debugging
  logger.error('Verification failed', {
    code: error.code,
    message: error.message,
    stack: error.stack,
  });
  
  // Return safe message to client
  res.status(401).json({
    error: getPublicMessage(error),
    code: error.code,
  });
}

Error Constants

Both SDKs export error code constants for type-safe error handling:

import {
  VALIDATION_ERRORS,
  SIGNATURE_ERRORS,
  DATE_ORDER_CODES,
  FRESHNESS_CODES,
  DATA_CATEGORY_CODES,
} from '@beltic/sdk';

if (error.code === SIGNATURE_ERRORS.EXPIRED) {
  // Handle expired token
}

if (FRESHNESS_CODES.includes(warning.code)) {
  // Handle any freshness warning
}

from beltic import (
    VALIDATION_ERRORS,
    SIGNATURE_ERRORS,
    DATE_ORDER_CODES,
    FRESHNESS_CODES,
    DATA_CATEGORY_CODES,
)

if error.code == SIGNATURE_ERRORS["EXPIRED"]:
    # Handle expired token
    pass

Overview

Getting started

Credentials

CLI

TypeScript SDK

Python SDK

Examples

Advanced

Reference

Error Code Format

Validation Errors (RV-*)

Date Order Errors

Freshness Warnings

Data Category Errors

Signature Errors (SIG-*)

Parsing Errors

Key Resolution Errors

Verification Errors

Trust Chain Errors (TC-*)

Policy Violation Errors (POL-*)

HTTP Signature Errors

Error Handling Best Practices

Categorize Errors

Log Details, Return Safe Messages

Error Constants

See Also

Overview

Getting started

Credentials

CLI

TypeScript SDK

Python SDK

Examples

Advanced

Reference

​Error Code Format

​Validation Errors (RV-*)

​Date Order Errors

​Freshness Warnings

​Data Category Errors

​Signature Errors (SIG-*)

​Parsing Errors

​Key Resolution Errors

​Verification Errors

​Trust Chain Errors (TC-*)

​Policy Violation Errors (POL-*)

​HTTP Signature Errors

​Error Handling Best Practices

​Categorize Errors

​Log Details, Return Safe Messages

​Error Constants

​See Also

Error Code Format

Validation Errors (RV-*)

Date Order Errors

Freshness Warnings

Data Category Errors

Signature Errors (SIG-*)

Parsing Errors

Key Resolution Errors

Verification Errors

Trust Chain Errors (TC-*)

Policy Violation Errors (POL-*)

HTTP Signature Errors

Error Handling Best Practices

Categorize Errors

Log Details, Return Safe Messages

Error Constants

See Also