Idempotency

Networks fail. If your request to start a run times out, you don't know whether RowCall got it. Retrying could call the shopper twice. Idempotency keys stop that.

Your requests to RowCall

Send an Idempotency-Key header, built from something unique in your system, with the requests that make something: start a run, cancel a run, make a flow and finish a pending action. The reference marks each endpoint that takes one.

curl -X POST https://app.rowcall.ai/v1/runs \
  -H "Authorization: Bearer $ROWCALL_API_KEY" \
  -H "Idempotency-Key: verify-4821" \
  -H "Content-Type: application/json" \
  -d @run.json

With the SDK, pass it as the last argument: rowcall.runs.start(input, { idempotencyKey: 'verify-4821' }).

• The same key with the same request within 24 hours gets the first response again, with the header Idempotent-Replayed: true. No second run is made.
• Refusals are kept too: a retry of a request refused with NO_CONSENT gets the same refusal. Use a new key once you've fixed the cause.
• A 5xx isn't kept, so retrying it runs the request again.
• The same key with a different request is refused with 422 and errorCode: "IDEMPOTENCY_MISMATCH".
• While the first request is still being answered, a retry gets 409 with IDEMPOTENCY_IN_PROGRESS. Wait a moment and retry.
• Keys are 1 to 255 printable characters, no spaces, and belong to the API key that sent them.

Use one key per thing you want to happen once: "verify order 4821", not "request number 7".

RowCall's requests to you

RowCall retries too, so your handlers must be safe to run twice.

• An action request carries an Idempotency-Key header, <callId>:<actionId>. Do the work once per key and return the same reply for repeats.
• A webhook event carries its id (also in the RowCall-Event-Id header). Store handled ids and skip repeats.