Major When an atom source sends an atom to a data engine, there are loosely three possibilities:
1. Success: The DE has received the atom, accepted it and will take responsibility for it.
2. Sender-Failure: The DE has received the Atom but cannot accept it (it is badly formed, missing mandatory fields etc).
3. Receiver-Failure: The DE has not received the Atom or has received it but cannot handle it at the moment or the caller used the wrong endpoint ( capacity, network failure etc).
In each of these cases, the sender knows what to do:
1 & 2: Forget about the Atom, don't send again.
3: Try to send the Atom again.
The BAP specifies return codes from Atom Post, but in Scheme 1 there are only two.
202 - is case 1 above
500 - sender cannot distinguish cases 2 or 3.
In scheme 2 there is a bit more detail, but there are only five codes stipulated and it is not explicit what the mapping would be:
202 - case 1
400 - case 2
404 - case 3 (wrong endpoint?)
500 - case 3 (internal error)
Suggestion is that we make these three cases explicit and be a bit less prescriptive on the return codes:
2xx - success, case 1 (some DE return 201, some 200)
5xx - failure case 3. Most likely a DE internal failure, sender can try again.
4xx - Mostly these are case 2 (badly formed) but there are also case-3 (unauthorised or forbidden) where the client can try again, albeit with correct credentials:
I would propose something simple:
400 - 1 or more atoms in the submission is badly formed and can never be accepted. If it is a batch, client can resubmit 1-by-1, if an individual atom, perhaps try once more in case transmission was garbled and then discard atom.
401/403: Client needs authorisation (does not say if the Atom is OK or not). Client can try again with right credentials
404: Endpoint not found, Client probably needs to try the information request, Does not say if Atom is OK or not so can try content again with right endpoint
Any other 4xx: If a batch, try each atom 1-by-1, if a single atom, just keep trying.
Question is what about an Atom that is syntactically correct but where the consumer or device ID is not known? The DE can 'accept' it (202) for association later, or reject it (perhaps with a 5xxx error) for the client to send later. Some discussion needed here.....