Idempotency
A network call can fail after Tillcast has accepted the request. If you simply send it again, you might queue a second job, and a second receipt prints. An idempotency key prevents that.
Send a key
Add an Idempotency-Key header of 1 to 64 visible ASCII characters to any call that creates something: a customer, a location, a printer, a job, or a test print. Use a value that is unique for the operation and the same on every retry of it, for example your own order id plus the kind of document. Create a print job shows a job sent twice, with the SDKs and with cURL.
What happens on a retry
“The same request” means the same operation, the same target and the same body, whatever the order of the keys in the body. A key is remembered for 24 hours, or for as long as its job can still print if that is longer. Keys are separate for each organization.
When you try a call by hand, use a new key each time. The same key with the same body answers with the first job again and prints nothing, which looks like a call that does not work. The same key with a different body is refused. Every example in these docs that sends a different request has a key of its own, so you can run two of them one after the other. If you change the body of an example, change its key too.
Two requests with the same key at the same moment make one object. One of them is answered 201 and the others are answered as replays (200 with Idempotent-Replayed: true) and carry the same object, so a client that retries too early, or two servers that handle the same event, still make one job. A concurrent create can also be answered 409 already_exists, which tells you to retry the request: send the same request again with the same key. See Errors.
A replay is answered before the state of the printer is looked at. A retry of a job that was accepted is not turned into 429 queue_full or 409 customer_suspended because the queue has filled or the customer has been suspended since.
When a replay returns a printer that was created with the key, the printer URL is null, because it is shown only once. Rotate the secret to get a new URL. A replayed create of a printer can also answer 503 printer_domain_unavailable while no printer domain is active, even though the first call succeeded.
A create that is refused writes nothing and leaves its key free for a request that is right.
Idempotency stops duplicate jobs from your retries. Tillcast delivers each job to a Star printer at least once, so after a power cut a Star printer can print the same job twice. Make a repeated print harmless. See Jobs.