Dropbox-API-Arg and accented filenames, the first bug of every French photo library

The Dropbox integration works perfectly in dev. First French user, first "Vacances à Éze.jpg" file, first 400 error.

The accent that breaks everything: the Dropbox-API-Arg header requires pure ASCII

Micro-post, pure gotcha format: one precise rule, never highlighted in tutorials, guaranteed to break on any French photo library.

The mechanism

Dropbox content endpoints (/files/download, /files/upload) do not take their parameters in the body: the body carries the binary. Parameters travel in a header, Dropbox-API-Arg, as JSON.

And an HTTP header, per spec, is ASCII. JSON, on the other hand, allows raw UTF-8. The two worlds collide exactly here:

POST /2/files/download
Dropbox-API-Arg: {"path": "/Photos/Vacances à Éze.jpg"}

The à and É fall outside ASCII: depending on the HTTP client, the request leaves corrupted or gets rejected. Dropbox answers with a 400 on header parsing, with a message that never points at encoding.

The fix: one line

JSON natively supports \uXXXX escaping, which produces pure ASCII. Escape every non-ASCII character after serialization:

String dropboxApiArg(Map<String, dynamic> args) =>
    jsonEncode(args).replaceAllMapped(
      RegExp(r'[^\x20-\x7E]'),
      (m) => '\\u${m[0]!.codeUnitAt(0).toRadixString(16).padLeft(4, '0')}',
    );

Before / after:

{"path": "/Photos/Vacances à Éze.jpg"}
{"path": "/Photos/Vacances \u00e0 \u00c9ze.jpg"}

Same JSON, same meaning, but the second form survives any HTTP client. It is exactly what the Dropbox docs recommend, in a paragraph nobody reads because everything works in English.

Why this bug is a classic

It passes every test written by developers who name their files test.jpg and photo_1.jpg. It waits for production, and for real users: "Noël 2025", "Randonnée forêt", "Bébé première année". On a French photo library, accented filenames are not an edge case, they are the majority.

One integration test with a single accented filename would have caught it. It is the kind of fixture I now add systematically during audits: a file named à É è ü 漢字.jpg triggers the whole family of encoding bugs at once.

Takeaways

Dropbox-API-Arg = JSON inside an HTTP header = ASCII mandatory.
Escape all non-ASCII as \uXXXX after jsonEncode: a one-line regex.
Put at least one accented filename in your test fixtures. Your users have hundreds.

What is the most exotic filename that ever broke one of your integrations?