Idempotency and safe retries

ThriveDesk does not currently honor an Idempotency-Key header. A repeated POST can therefore perform the action twice. This is especially important for replies: an automatic retry can send the same message to a customer more than once.

Prerequisites

• A bearer token with access to the write operation.
• A durable identifier for the action in your own system, such as a queued-job or outbound-message ID.

Safe retry contract

Store one record per intended write before calling ThriveDesk. Treat your identifier as unique, record the request state, and allow only one worker to own it at a time.

pending → sending → succeeded
                 ↘ unknown → reconcile before retrying
                 ↘ failed  → retry with backoff

If the connection fails after sending the request, the outcome is unknown. Do not immediately repeat a customer-visible write. First reconcile by reading the conversation and checking whether the expected reply or state change already exists.

const key = `reply:${conversationId}:${outboundMessageId}`;

if (await dedupeStore.hasSucceeded(key)) return;
await dedupeStore.claim(key);

try {
  await sendReply(conversationId, message);
  await dedupeStore.succeed(key);
} catch (error) {
  await dedupeStore.markUnknown(key, error);
  throw error;
}

Errors

• 422 means the request was rejected and can be corrected before retrying.
• 429 should be retried only after Retry-After.
• 5xx, connection resets, and timeouts can leave the outcome unknown.

Related

• Pagination and rate limits
• Errors
• Create tickets from your app