Bad requests will return an error, in the format:

<errormsg>Some Text about your naughtiness</errormsg>

<personalcombatkey>

is the parameter that was used to pull out this specific report. 

This parameter is unique to the player who received the mail and the combat it refers to.

However... many players may receive the same report (think of a joint defense of X city, or a Sally Forth), and - because personalcombatkey is unique to the player - you might end up requesting the same report multiple times.

So if you're really, truly looking for the unique identifier - or, rather, the parameters that make up an absolutely unique identifier for whether you already have this data, you need to use the data contained within the uniquecombatidentifier container.

<uniquecombatidentifier> <server id="UK1"/> <combatguid id="ABCDEFGHI-JKLMNOPQ-123456563ETC"/> <troopmovementevent id="1234567"/> <datacomplete id="1"/> </uniquecombatidentifier>

This combination of 4 things uniquely marks out a piece of combat data as original.

Obviously there is a remote chance that multiple servers might replicate the same GUID.

And obviously there is a 100% likelihood that multiple servers will replicate the same troopmovementevent (which is our internal incrementing identity field for unique combat events on each server).

But the combination of server, combatguid and troopmovementevent is impossible to come up again.

So this is your true, unique, primary key.

However!

The datacomplete variable is important too.  This flag essentially references whether the combat report you are reviewing at the moment is the complete truth. 

Examples (currently) of where it might not be the complete truth include where you send out a Raid against another army, and don't get the defenders' troop numbers back. In this case, all the data you have is "true" but incomplete.  This will become even more relevant with the Illusion schools of magic when they are introduced.

So the datacomplete field tells you the completeness of your report, and whether the new report is more "complete".

datacomplete of zero is less complete than datacomplete of one.  Please be aware that datacomplete is not a "bit" flag, and may extend through other levels of authoritativeness in the future.

So:

• If you already have a report for every variable in the uniquecombatidentifier container then you don't need to retrieve the new report - it'll be a duplicate of data you already have
  
  
• If you already have a report for every variable in the uniquecombatidentifier container except that the new report has a datacomplete higher value, then you should get this new report and replace your existing combat report with this new data, as it will contain everything your old report did, and then some more information on top