Skip to navigation

Rate limits and retention

How fast you can call the API, how big a job can be and how long data is kept.
View as Markdown

Rate limits

Tillcast does not limit the number of requests per key today. The limits that exist protect a printer and the service from loops:

LimitValueAnswer
Jobs waiting for one printer50429 queue_full, with a Retry-After header
Test prints for one printer5 in any minute, and 3 waiting at a time429 rate_limited, with a Retry-After header
New organizations3 per person, and 20 an hour in all429 rate_limited

A limited request gets HTTP 429. Wait for the number of seconds in Retry-After, then retry (queue_full sends 30). A queue empties as the printer prints, as you cancel jobs and as jobs pass their expires_at (24 hours by default), so do not retry queue_full in a loop. The SDKs wait for Retry-After inside the call, so one call can block for about a minute: see Retry safely. Handle 429 in your client now, so that a limit added later does not surprise you.

Be kind to the service even without a limit:

  • Lists that span a whole organization, such as all printers, are slower than a list by location or by customer. Prefer a list by location, and do not sweep large lists every few seconds.
  • Do not poll for job state faster than you need. A printer takes a job within about one poll interval, 5 seconds by default. Webhooks, which avoid polling, are planned and not built. See Webhooks and events.

Job limits

LimitValue
Blocks (document)1,000 blocks. Larger is 422 document_invalid. The same receipt written in ReceiptLine can be 256 KB of UTF-8 text, and larger is 413 document_too_large
ReceiptLine text (receiptline)256 KB of UTF-8 text. Larger is 413 document_too_large
What the document renders to256 KB of printer data, and 90 KB for the profile epson-legacy-80mm-42. Larger is 413 rendered_too_large
Request body800 KB for creating a job, 400 KB for every other request. Larger is 413 request_too_large
Waiting jobs per printer50. When the queue is full, new jobs are refused with 429 queue_full
Job lifetime24 hours by default. expires_in is 60 seconds to 7 days
Warnings per job21: the first 20, and too_many_warnings
client_reference_id1 to 128 characters
metadata10 pairs, 1 KB in all
Idempotency-Key1 to 64 visible ASCII characters, remembered for 24 hours

See Jobs and Receipt documents.

Retention

DataKept
Rendered receipt dataUntil the job is final. A job that never ends loses it from one hour after its expires_at, which is 7 days and one hour after the job is made at the latest, by a background clean-up that can be late. Tillcast does not keep the document you sent
Job state and outcome7 days after the job is final, and from 7 days after expires_at for a job that never ends, by a background clean-up that can be late
Audit entries of dashboard actions90 days. They are written now, and there is no endpoint to read them yet

Some data does not exist yet, because the features that make it are planned: printer state events (3 months), lifecycle events (1 year), the webhook delivery log (30 days), and usage statistics. Their periods are decided. The full table is in Security and data. There is no option to keep data longer, not even for a fee.