CONNECTOR SDK REFERENCE7 of 10
Error Handling
The SDK uses a standardized error model for consistent retries, alerts and diagnostics.
Be explicit
Use correct error code and category
Give context
Include correlationId, resource and operation
Safe data
Do not expose sensitive clinical data
Let Mediloop decide
Return errors — platform handles retry & routing
Log everything
Use ctx.logger with correlationId
Error model: MediloopConnectorError
typescriptCopy
export class MediloopConnectorError extends Error {
code: string; category: ErrorCategory; retryable: boolean;
httpStatus?: number; correlationId?: string; resourceType?: string;
constructor(params: MediloopConnectorErrorParams) {
super(params.message); Object.assign(this, params);
}
}Standard error codes
INVALID_REQUESTValidationNo400NOT_FOUNDNotFoundNo404CONFLICTConflictNo409UNAUTHORIZEDAuthenticationYes401FORBIDDENAuthorizationNo403RATE_LIMITEDRateLimitYes429UPSTREAM_ERRORUpstreamYes502TIMEOUTTimeoutYes504NETWORK_ERRORNetworkYes503INTERNAL_ERRORInternalYes500Error categories
ValidationRequest or data is invalid
AuthenticationAuth/token issues
AuthorizationUser not allowed
NotFoundResource does not exist
ConflictConflict with current state
RateLimitRate limit or throttling
UpstreamError returned by external system
NetworkTransport problems
TimeoutOperation timed out
InternalUnexpected internal failure
Retry strategy
Retryable: YesAutomatic retry with exponential backoff
Retryable: NoDo not retry
Error example
typescriptCopy
throw new MediloopConnectorError({
code:'RATE_LIMITED', category:'RateLimit', retryable:true,
httpStatus:429, message:'Upstream rate limit exceeded',
details:{limit:1000,retryAfter:30}, correlationId:ctx.correlationId
});Logging & correlation
typescriptCopy
ctx.logger.error({
event:'connector.error', error:err.toJSON?.() ?? err,
correlationId:ctx.correlationId, tenantId:ctx.tenantId,
resourceType:ctx.resourceType, operation:ctx.operation
}, 'Search operation failed');Dead-letter handling
Move repeatedly failing events/batches to DLQ
Review and fix root cause
Reprocess from DLQ via Console or API
Sensitive data
Do not include PHI in error messages
Mask tokens and secrets
Return minimal, safe details
Store full details securely only if needed
Quick checklist
Use correct error code
Set retryable based on error type
Include correlationId, resourceType, operation
Log with ctx.logger
Do not expose sensitive data
Test error paths