MACP

Errors API Reference

Error Hierarchy

Error
└── MacpSdkError           Base class for all SDK errors
    ├── MacpTransportError  gRPC connectivity issues
    └── MacpAckError        Runtime rejected the message

MacpSdkError

Base class for all SDK errors.

import { MacpSdkError } from 'macp-sdk-typescript';

const err = new MacpSdkError('something went wrong');
err.name;    // 'MacpSdkError'
err.message; // 'something went wrong'
err instanceof Error;        // true
err instanceof MacpSdkError; // true

MacpTransportError

Thrown when the gRPC transport fails (connection refused, timeout, etc.).

import { MacpTransportError } from 'macp-sdk-typescript';

try {
  await client.initialize();
} catch (err) {
  if (err instanceof MacpTransportError) {
    // gRPC layer error
    console.log(err.message); // e.g., '14 UNAVAILABLE: Connection refused'
  }
}

MacpAckError

Thrown when the runtime returns a negative acknowledgement (ack.ok === false).

import { MacpAckError } from 'macp-sdk-typescript';

try {
  await session.vote({ proposalId: 'p1', vote: 'approve' });
} catch (err) {
  if (err instanceof MacpAckError) {
    err.name;              // 'MacpAckError'
    err.message;           // 'SESSION_NOT_OPEN: session already resolved'
    err.ack;               // full Ack object
    err.ack.ok;            // false
    err.ack.error?.code;   // 'SESSION_NOT_OPEN'
    err.ack.error?.message;// 'session already resolved'
    err.ack.sessionState;  // 'SESSION_STATE_RESOLVED'
  }
}

Suppressing MacpAckError

Pass raiseOnNack: false to handle nacks manually:

const ack = await client.send(envelope, { raiseOnNack: false });
if (!ack.ok) {
  // handle rejection without exception
}

Runtime Error Codes

CodeDescription
UNAUTHENTICATEDAuthentication failed
FORBIDDENNot authorized for this session or message type
SESSION_NOT_FOUNDSession does not exist
SESSION_NOT_OPENSession already resolved or expired
DUPLICATE_MESSAGEmessage_id already accepted
INVALID_ENVELOPEValidation failed or payload invalid
UNSUPPORTED_PROTOCOL_VERSIONNo mutually supported version
MODE_NOT_SUPPORTEDMode or mode version not supported
PAYLOAD_TOO_LARGEExceeds size limit (default 1MB)
RATE_LIMITEDToo many requests
INVALID_SESSION_IDSession ID format invalid
INTERNAL_ERRORInternal runtime error