Skip to main content
A network error can leave you unsure whether ZeroGen received a request. To retry a POST safely, send an Idempotency-Key header with it. ZeroGen runs the request once for each idempotency key and answers a retry with the original outcome, so a retried create never starts a second run. Every POST endpoint accepts the header. Without it, each request runs on its own.

​
Choose an idempotency key

An idempotency key is 1 to 255 printable ASCII characters. Generate a new random value, such as a UUID, for each new request, and reuse it only to retry that request. ZeroGen keeps an idempotency key’s record for 24 hours. After that, the key can be used for a new request.

​
What a retry returns

ZeroGen fingerprints each request by its method, path, and JSON body. The order of keys in the body doesn’t matter. A retry with the same key and the same request returns the original outcome, with an Idempotent-Replayed: true header:
  • Creating a run. The retry returns the run’s current state, not a stored copy, so it can show progress since the first response. If the create was refused with a 4xx error, the retry returns that error.
  • Creating a folder or a label. The retry returns the original response. ZeroGen reserves the new folder’s or label’s ID under the key, so a retry after a failed first attempt makes it under that ID and never makes a second one. If the create was refused with a 4xx error, the retry returns that error.
  • Every other POST. The retry returns the original response.
A replay never starts new work. PATCH and PUT requests, such as renaming an asset or updating a label, don’t use Idempotency-Key, and ZeroGen ignores one sent with them. They set the values you send, so retrying one gives the same result.

​
Errors a retry can run again

ZeroGen doesn’t store an outcome that a retry could change: a 5xx error, a 429, or any error whose retryable is true. A retry with the same key runs the request again. For a create, the retry resumes the run, or makes the folder or label, under the ID the first attempt reserved instead of starting another, so you can retry a create until you get a stored outcome.

​
Conflicts

Each error’s param is Idempotency-Key.

​
Who shares an idempotency key

An idempotency key’s record belongs to the API key’s owner, the organization, and the API key’s mode:
  • Your other API keys. All of your API keys of one mode in an organization share records, so a retry still matches after you rotate an API key. A create that hasn’t started running yet is the exception: retry it with the API key that sent it, or send a new Idempotency-Key. A retry from another key returns 409 idempotency_conflict.
  • Live and test keys. A test key’s request never replays into, or blocks, a live request with the same idempotency key, or the reverse.
  • Other people and organizations. The same idempotency key from another member, or in another organization, is a separate record.