The docs for int playdate->file->rename(const char* from, const char* to); state:
Renames the file at from to to. It will overwrite the file at to without confirmation. It does not create intermediate folders. Returns 0 on success, or -1 in case of error.
(Emphasis mine)
But when running code like so:
SDFile* file1 = playdate->file->open("test1.txt", kFileWrite);
playdate->file->write(file1, "test", 4);
playdate->file->close(file1);
SDFile* file2 = playdate->file->open("test2.txt", kFileWrite);
playdate->file->write(file2, "test", 4);
playdate->file->close(file2);
int ret = playdate->file->rename("test1.txt", "test2.txt");
ret will be -1. And playdate->file->geterr() will return File exists.
Tested in the Windows simulator and on device with SDK 2.7.3.
Workaround is to unlink the file first, which can also fail if file to overwrite doesn't exist yet, so it's error must be ignored in those situations. You can't safely pre-check if it exists or not with stat as a file may exist with the same name in the .pdx, see here.
This may just be a documentation bug as the equivelant Lua function does not note the same functionality.