Skip to main content

Idempotency

A request that starts work — a session with a first message, a message, a generation — may time out after the work began. Retrying it blindly could start the work twice, and bill it twice. An Idempotency-Key makes the retry safe:

curl -s "$NEWEYES_API_BASE/v1/sessions/$SESSION_ID/messages" -X POST \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b7c5f1e-2d1a-4c4e-9a53-6c1f0e8b9d21" \
  -d '{"text": "Summarize what we found."}'
  • Generate a fresh key — a UUID is a good choice — for each piece of work, and send the same key, with the same request, when you retry it.
  • A retry with a key already used answers with the first answer, and starts nothing new.
  • A retry that arrives while the first request with its key is still being handled is refused with 409 idempotency_in_progress: wait for the number of seconds in its Retry-After header, then retry the same request with the same key.
  • The same key with a different request is refused with 409 idempotency_conflict. Do not retry it: a new request takes a new key.
  • A key is kept for 24 hours. A request that failed may be retried with its key.
  • Keys belong to the end user: two users never collide, even with the same key.

Operations that take the header say so in the API reference: creating a session, sending a message, and starting an image, video or music generation.

Retrying a streamed message​

A message sent with "stream": true answers with its task's event stream. How the answer is delivered is not part of the request: a retry with the same key — streamed or not — returns the same task, and a streamed retry sends it again from its first frame. See Event streams.