How to deal with a poorly documented AWS SQS feed for a security product API?

The thing with API's is that they are designed for computer use, not human.

From the computers viewpoint the string error message is useless. You have all the info you need in the event code and fields to construct your own message in various languages etc.

What I think is happening here is that the devs have just exposed the raw log messages. $1, $2 etc are just the parameters sent when calling the logger in the order they are in the code. ie

console.log(“%3$s: open, %1$s in %2$s”, "detector name", "room name", "device type");

If the dev is copying and pasting, you might find that the order of the parameters is generally the same, but there no reason some device code else where might have

console.log(“%1$s: open, %2$s in %3$s”, "device type", "detector name", "room name");

My advice would be to ignore the message template entirely. Use the event code to look up the intent of the message and construct your own plain english version of it as required.

When I encounter poor documentation I generally go to the source code, initial design documentation, blame.

If I am not banned from the organization or repository I notify the maintainers about the issue with the documentation.

If I am banned from the organization or repository I try to reach out to developers in the field to fix the documentation with a roadmap I provide.

During the process I generally write a gist on GitHub explaining what is undocumented, what I discovered in source code comments, blame, etc., and update the gist. That provides some form of documentation for myself and other developers that might find themselves in the same situation.

There's a few errors or omissions on MDN that I have brought to the attention of stakeholders and developers. Some have current PR's to fix the errors or omissions, some just languish right now as simply wrong on MDN.

Sometimes specifications themselves can be ambiguous, leaving room for "host implementations" to do or not do whatever they want in a given scenario; for example dynamic import() in ECMA-262.

Sometimes implementers ignore specifications and do what they want; e.g., in the case of WHATWG Fetch and full-duplex streaming.

What I would do is start the documentation process in a gist based on what you find in tests for the specific parameters and results you get.