Skip to main content

Idempotency

A network failure can leave you without a response, so you do not know whether Nodu processed your request. An idempotency key lets you recover a stored successful response to the same POST request. Nodu keeps that response for 24 hours. After an uncertain outcome, check whether the operation completed before retrying: see Retry a request that timed out. Your own clientReferenceId can help match the result to your records and complement idempotency handling.

Send an idempotency key​

Add the Idempotency-Key header to a POST request:

Idempotency-Key: 8f14e45f-ceea-467f-a9d1-8b0c2f1d3a77
  • The value is a string that you choose, up to 255 characters long. Nodu refuses a longer value with a 422 validation error.
  • Use a new value for each operation. A version 4 UUID is a good choice. Two transfers with the same body need two keys: with one key, the second request returns the first transfer.
  • Nodu applies the header to POST requests only. On GET, PUT, PATCH and DELETE requests Nodu ignores it.
  • The header is optional. Without it, Nodu processes every POST request as a new request.

Send the header with every POST request that creates an object or moves money, such as Create a customer and Create a transfer.

How Nodu handles a key​

RequestWhat Nodu does
The first request with a keyProcesses the request. If it succeeds, Nodu stores the request body and the response for 24 hours.
A stored successful result, with the same key and body, within the 24 hoursReturns the stored response, with the same status code and the same body. Nodu does not perform the operation again.
A stored successful result, with the same key but a different body, within the 24 hoursRefuses the request with 409 Conflict and code=idempotency_mismatch. Restore the original body to recover the stored response.
The same key after the 24 hoursProcesses the request as a new request.

Two details decide whether Nodu treats a request as a repeat:

  • Nodu compares the body exactly as you sent it. The same JSON with different spacing or a different field order counts as a different body.
  • A key belongs to the API key and the endpoint that it was sent to. The same value sent with another API key, or to another endpoint, is a new key for Nodu. Retry with the same API key you used for the first request.

A 409 with code=resource_busy can mean an earlier request with the same key is still running. Other resource conflicts have their own recovery actions: see Errors and rule codes.

When Nodu does not store a result​

Nodu stores a result only when the request succeeds, that is, when the response status is 2xx. Nodu does not store an error response. When no successful response is stored, a retry is processed again. An operation can complete before its response fails, so a server error does not prove that nothing happened.

  • After a validation error or a business rule violation, correct the cause. Send the request again with the same idempotency key or a new one.
  • A request that arrives while Nodu is still processing an earlier request with the same key waits for it. If the earlier request is still running after the wait, Nodu answers 409 with code=resource_busy and a Retry-After header. Send the request again with the same key and exact body.

Retry a request that timed out​

When a POST request times out, the connection drops, or Nodu returns 500, the outcome is unknown. Before the first request, store the idempotency key, the exact request body and your reference for the operation.

Check the resource's current state, list results and webhook events before retrying. For transfers, follow Reconcile with the list. An operation can complete without a stored successful response; retrying even with the same key can then perform it again. If you cannot establish the outcome, contact Nodu before creating a replacement or releasing reserved funds.

When you retry, use the same key, API key, endpoint and exact body within 24 hours:

  • If Nodu stored a successful response, you receive that response without repeating the operation.
  • If no successful response is stored, Nodu processes the request again.

Do not create a new key to recover an uncertain result. After 24 hours, the stored response expires: reconcile before sending another request, even with the original key.

Use clientReferenceId with idempotency​

clientReferenceId is an identifier from your own system, such as your internal id of the customer. You send it in the body of a create request. Nodu stores it with the object and returns it in the object. Unlike an idempotency key, it does not expire.

Use a stable value from your records to connect a request, its response and later webhook events. Keep the returned Nodu id alongside it. The API Reference describes each operation's reference constraints and available filters.

Continue to use Idempotency-Key for retries: it returns a stored successful response within the retention period. If an operation returns resource_conflict, check the existing object before deciding whether to create another one.

Retry decisions​

ResultNext action
Timeout, dropped connection or 500Reconcile the outcome first. When retrying, use the same key and exact body within 24 hours; contact Nodu if the outcome remains uncertain.
409 with code=resource_busyWait the number of seconds in Retry-After, then retry with the same key and exact body.
409 with code=idempotency_mismatchRestore the original body to recover its result. Use a new key only for an intentionally separate operation.
Validation error or business rule violationCorrect the input or resolve the state conflict before trying again.
Another resource_conflictFollow the recovery action in Errors and rule codes.
Key older than 24 hoursReconcile first; the expired key no longer protects a retry.

Next steps​