get_note_outline returns block positions as raw integers. Any write invalidates them – silently, until a follow-up call errors with INVALID_POSITION. By then, you've lost track of what you were doing and have to fetch the outline again from scratch.

A revision token attached to both the outline response and write calls would let clients detect staleness before making the call, not after. Even a lastModified timestamp would help. Right now, the API just asks you to guess.