Retries

Networks drop requests. When a request times out, you can't always tell whether it reached Rookery. Whether it's safe to send again depends on what it does.

Safe to retry

Doing these twice has the same result as doing them once:

• every GET: reading and listing;
• Change status: setting the same status again changes nothing;
• Tag or untag: a tag that's already there isn't added twice;
• Assign: assigning to the same person again changes nothing.

Check before retrying

These make something new each time, so a retry can make a second one:

• Add an internal note;
• Reply to the customer;
• Ask the customer for documents.

There's no Idempotency-Key header yet. After a timeout on one of these, read the conversation first, and only retry if yours isn't there:

1. Call Read a conversation with the same id.
2. Look at the end of the timeline:
   • a note shows as "type": "note" with your key's name as author;
   • a reply shows as "type": "message", "direction": "outbound", with "status": "draft" (or scheduled if it was sent) and your text.
3. If it's there, the first request worked. If not, send it again.

A doubled draft is easy to fix: it waits in Needs your yes, and the person approving can throw one away. That's one more reason to draft, not send.

Each operation in the OpenAPI spec says whether it's safe to retry, in x-rookery-idempotent.

Coming later

An Idempotency-Key header for requests that create things, so a retry with the same key returns the first answer instead of doing it twice. It will be optional, and calls without it will work as they do now.