Error Handling & Operations

Error Handling & Operations

Auto-Reconnect Mechanism

The SDK has built-in auto-reconnect; no developer handling is needed:

FeatureBehavior
Connection lostAuto-reconnect with 3-second delay
Retry countInfinite retries (until release() is called)
HeartbeatPing sent every 10 seconds
Token refreshNew JWT generated on each reconnect (1-hour validity)
After reconnectionRobot will resend online events

Auth Callback

java
agentSdk.registerAuth((appId, code, msg) -> {
    switch (code) {
        case 0    -> log.info("Authentication successful");
        case 1001 -> log.error("Token expired (should not occur, SDK auto-refreshes)");
        case 1004 -> log.error("Signature verification failed, check appKey / appSecret");
        case 5    -> log.error("WebSocket handshake failed");
        case 6    -> log.error("Unknown exception: " + msg);
        default   -> log.error("Authentication error: code={}, msg={}", code, msg);
    }
});

Returning Business Errors via Response

When SDK-side processing fails, notify the robot via response.onError():

java
@Override
public void onRequest(String agentId, String eventId, int flag,
                      byte[] buf, AgentParam param, Audio2LlmResponse response) {
    try {
        // Business processing...
    } catch (Exception e) {
        response.onError(eventId, 5001, "ASR service timeout");
    }
}

Error Code Conventions

Error code ranges are partitioned by responsible system (which system produced the code). Integrators should branch on code, not parse message text. See dep/AgentErrorCode错误码规范.md for the full contract.

RangeResponsible systemExamples
0SuccessAuthentication success, request acknowledgment success
1-999AgentSdk itself (never touches network)Connection already closed, payload validation failure
1000-1999二开网关 (linksoul-linksky)1001=Token expired, 1004=Signature error, 1003=Robot offline
2000-2999交互网关 (aiem-emp)Session/scheduler not found
3000-3999Robot sideRobot execution failed
4000-4900Integrator-defined business errorsDeveloper-defined, values not specified by the SDK

Resource Release

java
// Release SDK instance (disconnect, clean up all registered callbacks and caches)
agentSdk.release();

release() performs the following:

  1. Sets the released flag, stops auto-reconnect
  2. Closes the WebSocket connection
  3. Cleans up callbackType registrations
  4. Cleans up all internal state mappings

Note: After release(), you can call create() again with the same appId to obtain a new instance.

Logging Configuration

The SDK uses SLF4J + Logback. Recommended configuration:

xml
<!-- Normal operation -->
<logger name="com.agibot.aiem.sdk" level="INFO"/>

<!-- Debug message sending/receiving -->
<logger name="com.agibot.aiem.sdk.client" level="DEBUG"/>

<!-- Debug thread pool -->
<logger name="com.agibot.aiem.sdk.mgr" level="DEBUG"/>

Troubleshooting

SymptomPossible CauseHow to Investigate
Auth failed code=1004Wrong appKey / appSecret, or signature payload mismatchVerify appKey / appSecret; signature payload must be "GET\n{path}\n{timestamp}\n{nonce}"
Connected but no messages receivedCallback registered after initialize()Ensure callbacks are registered before initialization
onRequest not being calledRobot not online or callbackType mismatchCheck if onRobotOnline fires
Response method calls have no effectResponse already cleaned up (120s timeout)Ensure processing takes less than 120 seconds
Memory keeps growingrelease() not called or many agentIds not going offlineCheck robot lifecycle management