Skip to content

DevelopersEssentials

Retries and idempotency

Networks fail: a request can time out after the API has already done the work. This page shows which requests you can simply send again, and how to avoid booking or creating something twice when you can't tell whether the first attempt went through.

On this page

What’s safe to retry

RequestRetry as is?Why
GETYesReads never change anything.
PATCHYesIt sets fields to the values you send; sending the same values twice ends the same way. Moving an appointment to the time it already has doesn’t email anyone again.
POST …/cancel, PATCH /messages/{id}YesCanceling a canceled appointment, or resolving a resolved message, returns it unchanged.
DELETEYesIf the first attempt worked, the retry gets 404 resource_missing: treat that as done.
Other POSTsCheck firstThey create something (an appointment, contact, article, webhook or client). Sent twice, some create two.
The API doesn't support an Idempotency-Key header. Use the checks below instead.

Creating things safely

Several creates refuse a duplicate on their own, which makes a retry harmless:

  • Contacts are unique by phone number. Creating one that exists returns 409 contact_exists; look it up with GET /v1/contacts?phone=… and update it instead.
  • Appointments can't overlap. A retried booking for the same time returns 409 slot_taken, so check whether it's yours (same time and name) before telling anyone the slot is gone.
  • Clients (partner API) are unique by owner email: a retry returns 409 email_taken.

Knowledge articles and packages, and webhook endpoints, have no natural key: a repeated POST creates a second one. After a timeout, list them and look for yours before sending it again. For webhooks, two endpoints with the same URL would get every event twice.

# The POST timed out. Before sending it again, look for the appointment it may have made:
curl "https://api.assistcall.ai/v1/appointments?starts_after=2026-11-03T15:00:00Z&starts_before=2026-11-03T15:00:01Z" \
  -H "Authorization: Bearer $ASSISTCALL_TOKEN"

Timeouts

  • Give requests a client-side timeout of about 30 seconds. The API answers or gives up within 25 seconds (503 timeout).
  • A 503 or a dropped connection on a write means the outcome is unknown: check, as above, before repeating it.
  • A 4xx answer means nothing changed (except a 409, which tells you something already exists).

Emails and notifications

Some writes can email people: notify: true on appointments emails the customer, and creating a client or resending an invite emails the owner. Make sure a retry can't send these twice: check first, and send notify only on the attempt you know is the first.

Duplicate webhook deliveries

The other direction matters too: a webhook can arrive more than once (we retry when your endpoint doesn't answer 2xx in time). Store each event's id and skip ones you've already handled.

Try "token", "webhook signature", "rate limit" or "custom domain".