Error Handling & Operations

Auto-Reconnect Mechanism

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

Feature	Behavior
Connection lost	Auto-reconnect with 3-second delay
Retry count	Infinite retries (until `release()` is called)
Heartbeat	Ping sent every 10 seconds
Token refresh	New JWT generated on each reconnect (1-hour validity)
After reconnection	Robot 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 1005 -> log.error("WebSocket handshake failed");
        case 1006 -> 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

Range	Meaning	Examples
0	Success	Authentication success, request acknowledgment success
1000-1999	Authentication/connection errors	1001=Token expired, 1004=Signature error
2000-2999	Protocol errors	Message format error
3000-3999	Gateway errors	Routing failure
4000-4999	Robot-side errors	Robot not online
5000-5999	SDK-side business errors	Developer-defined errors

Resource Release

java

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

release() performs the following:

Sets the released flag, stops auto-reconnect
Closes the WebSocket connection
Cleans up callbackType registrations
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

Symptom	Possible Cause	How to Investigate
Auth failed code=1004	Wrong appKey / appSecret, or signature payload mismatch	Verify appKey / appSecret; signature payload must be `"GET\n{path}\n{timestamp}\n{nonce}"`
Connected but no messages received	Callback registered after initialize()	Ensure callbacks are registered before initialization
onRequest not being called	Robot not online or callbackType mismatch	Check if onRobotOnline fires
Response method calls have no effect	Response already cleaned up (120s timeout)	Ensure processing takes less than 120 seconds
Memory keeps growing	release() not called or many agentIds not going offline	Check robot lifecycle management