Idempotency-Key

An idempotency key lets you retry a POST request without risking doing the work twice. If a network error, a timeout or a crash leaves you unsure whether Meetingize received your request, send it again with the same key: you get the original response back instead of a second meeting, a second document or a second charge.

How do I use it?

Add an Idempotency-Key header to any POST request. Use a unique value per operation, typically a UUID v4 generated when you decide to perform the action (not when you send the request):

KEY=$(uuidgen)
curl -s -X POST "https://app.meetingize.com/api/v1/meetings/$MEETING_ID/documents" \
  -H "Authorization: Bearer $MEETINGIZE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"template_id": "tpl_42"}'
# Network error? Send exactly the same request with the same $KEY.

Store the key with the operation in your system (for example on the CRM record that triggered it) so that a retry after a restart reuses it.

What happens when I retry?

Situation	Response
First request with this key	processed normally
Same key, same body, first request finished	the original response is replayed (same status, same body), with the header Idempotent-Replayed: true. Nothing is executed or billed again
Same key, same body, first request still running	409 idempotency_key_in_use: wait a moment and retry
Same key, different body	422 idempotency_key_reused: a key identifies one operation, generate a new one for a new operation

For multipart uploads, the comparison covers the form fields and the uploaded file (name, size and SHA-256), so the same file with the same key is recognized as a retry.

Good to know

• Keys are remembered for 24 hours. After that, the same key is treated as a new operation.
• Keys are scoped to your account: two accounts cannot collide.
• GET requests are naturally safe to retry and ignore the header.
• Any string up to 255 characters works; UUIDs are recommended.
• The MCP server sends an idempotency key on every confirmed write action, derived from the action and its arguments, so an AI assistant retrying a tool call never starts the same job twice.