Errors API Reference
Error Hierarchy
Error
└── MacpSdkError Base class for all SDK errors
├── MacpTransportError gRPC connectivity issues
└── MacpAckError Runtime rejected the messageMacpSdkError
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; // trueMacpTransportError
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
| Code | Description |
|---|---|
UNAUTHENTICATED | Authentication failed |
FORBIDDEN | Not authorized for this session or message type |
SESSION_NOT_FOUND | Session does not exist |
SESSION_NOT_OPEN | Session already resolved or expired |
DUPLICATE_MESSAGE | message_id already accepted |
INVALID_ENVELOPE | Validation failed or payload invalid |
UNSUPPORTED_PROTOCOL_VERSION | No mutually supported version |
MODE_NOT_SUPPORTED | Mode or mode version not supported |
PAYLOAD_TOO_LARGE | Exceeds size limit (default 1MB) |
RATE_LIMITED | Too many requests |
INVALID_SESSION_ID | Session ID format invalid |
INTERNAL_ERROR | Internal runtime error |