Retrying writes

How to repeat a write after a dropped connection without creating a duplicate.

Why

Networks are unreliable. You sent a request to create a contact, the answer never arrived — and you do not know whether the contact exists. Retrying is scary: you may end up with two identical contacts.

That is what the Idempotency-Key header is for.

How to use it

Make up a unique string per logical operation (a UUID is fine) and attach it:

curl -X POST "https://api.tg-desk.com/v1/contacts" \
  -H "Authorization: Bearer $TYGY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f1c8e40-1f2a-4b6d-9d3e-7a5c1b2d3e4f" \
  -d '{"name": "Ivan Petrov", "email": "ivan@example.com"}'

If the answer never arrived, repeat the request with the same key and the same body. We return the stored answer of the first request instead of doing the work twice. The replay carries a header:

Idempotency-Replayed: true

Rules

• The key works on every writing method: POST, PATCH, PUT, DELETE.
• A key lives for 24 hours, then it is forgotten.
• A key is scoped to your project.
• At most 255 characters.
• The same key with a different body is an error. A 422 with code idempotency_mismatch. That guards against accidentally reusing a key: otherwise you would silently get the answer to a completely different operation.
• Failures are not stored. If the first attempt died with a 500, a retry with the same key genuinely runs again — by design.

When you do not need it

Some operations are safe on their own. Adding a tag that is already there, or closing an already-closed conversation, changes nothing and breaks nothing. The key matters where a repeat creates something new: a contact, an organization, a message, a webhook subscription.