Concepts

Retries and idempotency

Write requests accept an Idempotency-Key header, so retrying a request never creates a second invoice.

Idempotency keys

Generate a unique value, such as a UUID, for each operation and send it with the request. If the connection drops or you get a 5xx response, retry with the same key. Neno recognises it and returns the original result instead of doing the work twice. Keys can be up to 255 characters.

curl -X POST https://api.neno.co/public/v1/invoices \
  -H "Authorization: Bearer $NENO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5d0f6b1e-2c47-4b8e-9a31-7e2f4c8d9b60" \
  -d @invoice.json

Conflicts

Sending a key again with a different body returns 409 Conflict. It usually means two different operations were given the same key. Create a new key for each operation, and reuse it only when retrying that operation.