Error Handling

Result codes

Every method call returns a result code alongside the response JSON:

Code	Name	Meaning
0	OK	Success. Response JSON contains the result.
1	ERROR	Failure. Response JSON contains an error object.
2	NOT_SUPPORTED	Plugin does not implement this method.

The SDK returns NOT_SUPPORTED automatically for any method not listed in GetInfo.capabilities. You only need to handle OK and ERROR.

Error response format

When a method fails, the response JSON must be:

{
  "error": {
    "code": "CONNECTION_FAILED",
    "message": "Could not connect to ERP server sql-erp-prod: timeout after 5s."
  }
}

code is a machine-readable string. message is a human-readable description shown to the user.

Using PluginException in C

Throw PluginException to return an ERROR result with a structured error object:

throw new PluginException("NOT_FOUND",
    $"Article code '{articleCode}' not found in ERP.");

throw new PluginException("CONNECTION_FAILED",
    "Could not reach ERP server. Check your network connection.");

throw new PluginException("ACCESS_DENIED",
    "Your account does not have permission to check out files.");

Any unhandled exception is caught by the SDK and returned as:

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unhandled exception: Object reference not set to an instance..."
  }
}

Standard error codes

Use these codes consistently so HydroSym and users can recognize common failure modes:

Code	When to use
NOT_FOUND	The requested item (article code, project ID, file) does not exist in the external system
CONNECTION_FAILED	Could not connect to the database, ERP, or PDM system
AUTHENTICATION_FAILED	Credentials are wrong or expired
ACCESS_DENIED	The current user does not have permission for this action
CONFLICT	The file is already checked out by another user
VALIDATION_ERROR	The request data is invalid (e.g., malformed article code)
TIMEOUT	The external system did not respond in time
INTERNAL_ERROR	An unexpected error in the plugin itself

You may define additional codes for your integration. Prefix them with your vendor name to avoid clashes: ACME_QUOTA_EXCEEDED.

How HydroSym displays errors

• WARNING-level errors (e.g., NOT_FOUND from GetComponentParameters): HydroSym shows a warning badge or tooltip on the affected component. The workflow continues.
• BLOCKING errors (e.g., CONNECTION_FAILED from Initialize): HydroSym shows a dialog and, depending on the method, may halt the workflow.
• Workflow-critical errors (e.g., CONFLICT from CheckOut): HydroSym shows a dialog and does not open the file.

What happens when a plugin crashes

DLL transport: An unhandled native exception propagates up through HydroSym's call stack. HydroSym's crash handler (EurekaLog) catches it. The user sees a crash report. HydroSym must be restarted.

Process transport: The plugin process terminates. HydroSym detects the closed pipe and shows an error dialog. HydroSym itself keeps running. The plugin is marked as unavailable for the session.

This is one reason to prefer process transport for plugins that are less stable or use third-party libraries.

Error handling checklist

• [ ] Wrap all external calls (database, HTTP, file I/O) in try-catch.
• [ ] Always throw PluginException with a meaningful code and message.
• [ ] Never let NullReferenceException or InvalidOperationException propagate — they produce unhelpful error messages.
• [ ] Log detailed error information internally (to a file or the Windows Event Log) and show only a user-friendly summary in the PluginException message.
• [ ] For Initialize, fail fast with a clear message if the config is missing or the server is unreachable.