Skip to main content

Idempotent mutations

Submarine supports an Idempotency-Key header to reduce the risk of mutations with side effects (such as the creation of new resources) being duplicated. Simply pass the header in your GraphQL request, and Submarine will ensure that the mutation is run only once, caching the result of the first run.

curl -X POST https://api.submarineplatform.com/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SUBMARINE_API_KEY" \
-H "Idempotency-Key: 1f0c7a0e-5b8e-4f43-9c4e-2d1b8f6a9e21" \
-d '{"query": "mutation ($input: PresaleCampaignCreateInput!) { presaleCampaignCreate(input: $input) { presaleCampaign { id } userErrors { field message } } }", "variables": {"input": { ... }}}'

Note that idempotency only applies to mutations and read-only queries will silently ignore it.

Choosing a key​

A key is any string of up to 255 characters. If more than one event in your own system can trigger the same change, such as a webhook that arrives twice, derive the key from what's being changed. For example, presale-campaign-create:<product id> would give both attempts the same key and ensure that only a single presale campaign is created for the given product ID (within a 24 hour period).

What a retry gets​

When you retry with the same key and…you get
the first request finished, with the same query and variablesthe stored result of the first request.
the first request is still runningIDEMPOTENCY_CONCURRENT_REQUEST. Wait, then retry with the same key.
the query or variables are differentIDEMPOTENCY_KEY_PARAMETER_MISMATCH. Use a new key for a different request.
the first request failed with an internal errorIDEMPOTENCY_PREVIOUS_ATTEMPT_FAILED. Check whether the change happened, then use a new key.

A key longer than 255 characters gets IDEMPOTENCY_KEY_INVALID.

Send each retry exactly as you sent the first request. A changed query, or the same variables in a different order, can count as a different request and get IDEMPOTENCY_KEY_PARAMETER_MISMATCH.

A response with userErrors counts as finished, so a retry with the same key gets those errors again. Fix the input and send it with a new key. A request that fails GraphQL validation, such as one with a variable of the wrong type, doesn't use its key.

Keys last 24 hours from the first request. After that, the same key runs the mutation again.

Reading the error codes​

The codes arrive in the nested errors list of a GraphQL error:

{
"data": { "presaleCampaignCreate": null },
"errors": [
{
"message": "Failed to fetch from Subgraph 'platform-presales'.",
"extensions": {
"serviceName": "platform-presales",
"errors": [
{
"message": "A request with this idempotency key is still running. Retry with the same key once it finishes.",
"extensions": { "code": "IDEMPOTENCY_CONCURRENT_REQUEST" }
}
]
}
}
]
}

Several mutations in one request​

You can send several mutations in one request under one key. Submarine keeps each mutation's response separately, so a retry replays each mutation that finished and returns an error for any that failed.