0x8D03 is a transient "transfer already in progress" state, but is reported as 400 "Failed to start file download"

[jordlee]

Environment: ILCE-7M5 (CFCA6014E092) · USB · Camera Remote SDK V2.02.00 · darwin-arm64 (macOS 15) · server 3.0.0 · remote-transfer

Summary

0x8D03 (CrError_RemoteTransfer_GetContentsDataDisable) is a transient, retryable "a transfer is already in progress" condition, not a failure of the requested transfer. The server surfaces it as:

HTTP 400 {"message":"Failed to start file download: 0x00008D03","success":false}

That wording says the download failed and implies a permanent fault. Both are wrong: the request was simply issued while another transfer was in flight, and the identical request succeeds moments later.

Deterministic reproduction

Connect in remote-transfer, then:

Step	Request	Result
1	POST .../131082/2/download (67.8 MB)	202
2	POST .../131305/1/download — 0.3 s later, while step 1 is in flight	400 0x8D03
3	wait for step 1 to complete (~20 s)	—
4	repeat step 2 verbatim	202, completes normally

Recovery is immediate — a retry 2 s after the in-flight transfer finished already succeeded in my run. No reconnect, no restart, no replug.

Why this matters beyond the wording

This misreporting produced the wrong causal model in #40. There, one transfer hung permanently (a Linux-only defect), so every later transfer correctly reported "busy" — for the rest of the session. Read through this message, that looked like "one failed download latches the whole RemoteTransfer subsystem into 0x8D03", and the investigation went hunting for a latching mechanism that does not exist. See #40 for the correction.

A retryable-busy state reported as a hard failure is the kind of thing that costs a day of debugging exactly once per person who hits it.

Expected

• 409 Conflict (or 503 with Retry-After) rather than 400.
• A message that names the actual state and the remedy, e.g. "A transfer is already in progress on this camera. Retry when it completes — watch for transferProgress."
• Ideally include the in-flight transfer's identity (content/file id) so a client can wait on the right event.

Related: the underlying lack of queueing is filed separately.

[jordlee]

Fixed in #54 (not yet merged)

Commit 20a446d. 0x8D03 now returns 409 with retryable: true and a message naming the state and the remedy:

HTTP 409
{
  "success": false,
  "retryable": true,
  "message": "A transfer is already in progress on this camera, so the file download was not started. This is transient — retry once the current transfer completes (watch for a transferProgress event). SDK error 0x00008D03."
}

Implemented as a shared classifyTransferError() used by both the full-file and thumbnail/screennail paths, so the two cannot drift. The outcome is also logged at warn/error — these paths previously logged nothing beyond the request line, which is a large part of why the underlying condition in #40 was so hard to see.

Verified on hardware (ILCE-7M5, macOS, SDK V2.02.00): a second request issued 0.3 s into a 67 MB transfer returns 409; the identical request returns 202 once that transfer completes.

0x8D02 deliberately keeps its existing 400 and message — it is the genuinely different case (identifiers not valid for the connection mode), and a regression check confirms it was not swept into the new branch.

Docs updated in the same PR: web-api/sd-card now documents the one-transfer-at-a-time constraint and the 409 body.

The commits say Refs #49 rather than Fixes, so this will not auto-close — worth closing by hand once #54 lands. The underlying inability to queue rather than reject is separate and still open as #50.