{"record":{"id":"1d1c94a42a356736","repo":"aeron-io/aeron","slug":"unexpected-response-code-code","errorCode":null,"errorMessage":"unexpected response code: <code>","messagePattern":"unexpected response code: <code>","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java","lineNumber":2443,"sourceCode":"                final ArchiveException ex = new ArchiveException(\n                    \"response for correlationId=\" + correlationId + \", error: \" + poller.errorMessage(),\n                    (int)poller.relevantId(),\n                    poller.correlationId());\n\n                if (poller.correlationId() == correlationId)\n                {\n                    throw ex;\n                }\n                else if (context.errorHandler() != null)\n                {\n                    context.errorHandler().onError(ex);\n                }\n            }\n            else if (poller.correlationId() == correlationId)\n            {\n                if (ControlResponseCode.OK != code)\n                {\n                    throw new ArchiveException(\"unexpected response code: \" + code);\n                }\n\n                return poller.relevantId();\n            }\n        }\n    }\n\n    private boolean pollForResponseAllowingError(final long correlationId, final int allowedErrorCode)\n    {\n        final long deadlineNs = nanoClock.nanoTime() + messageTimeoutNs;\n        final ControlResponsePoller poller = controlResponsePoller;\n\n        while (true)\n        {\n            pollNextResponse(correlationId, deadlineNs, poller);\n\n            if (poller.controlSessionId() != controlSessionId)\n            {","sourceCodeStart":2425,"sourceCodeEnd":2461,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/client/AeronArchive.java#L2425-L2461","documentation":"Thrown by awaitRelevantId (and similar response awaiters) when the archive replies for the expected correlationId with a control response whose code is not OK. The ArchiveException message carries the ControlResponseCode value, and relevantId/error details on the poller explain the underlying rejection.","triggerScenarios":"Any call using awaitRelevantId (e.g. startReplay returning replay sessionId) where the archive responds with ERROR or an unexpected code for the matched correlationId - e.g. unknown recordingId, no available replay, or session errors.","commonSituations":"Requesting a replay for a deleted/unknown recording; archive rejecting a request due to exhausted replay resources; protocol/version mismatch between client and archive producing an unrecognized code.","solutions":["Inspect the ArchiveException error code (e.errorCode()) and the archive log for the root cause of the non-OK response.","Validate the recordingId exists (listRecording) before operations that expect an OK response.","Ensure client and archive versions are compatible (same protocol version).","Handle expected error codes explicitly rather than treating every non-OK as fatal."],"exampleFix":"// before\nint sessionId = archive.startReplay(recordingId, position, length, replayChannel, replayStreamId);\n// after\ntry {\n    int sessionId = archive.startReplay(recordingId, position, length, replayChannel, replayStreamId);\n} catch (ArchiveException e) {\n    if (e.errorCode() == ArchiveException.UNKNOWN_RECORDING) {\n        // verify recording exists / was purged\n    }\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"// verify recording exists before replay\narchive.listRecording(recordingId); // throws RecordingSignal/position errors if absent","typeGuard":null,"tryCatchPattern":"try {\n    int session = archive.startReplay(recordingId, pos, len, ch, streamId);\n} catch (ArchiveException e) {\n    if (e.errorCode() == ArchiveException.UNKNOWN_RECORDING) { /* handle */ }\n    else throw e;\n}","preventionTips":["Validate recordingId existence before replay-creating calls.","Keep client and archive protocol versions aligned.","Log errorCode() and relevantId for every archive rejection."],"tags":["aeron-archive","control-response","protocol"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}