Label API Errors, Retries, Job Limits, and PDF Retention

Decide whether to fix a request, check an existing job, wait for capacity, or download a completed PDF without accidentally submitting it twice.

G Gookit Team

· September 20, 2026 · 5 min read

When a label request fails, first identify which operation stopped: submission, background rendering, status checking, or file download. The recovery action depends on that phase.

A successful POST /print returns 202 and a job ID. It does not mean the PDF is ready. Save that ID and check the existing job before deciding to submit another batch.

Choose the next action from the response

These responses are documented in the Gookit API reference, checked September 20, 2026. In our small live test, a missing key returned 401 and a zero quantity returned 400; we did not deliberately exhaust the account or trigger every limit.

Signal	Likely next action
`400`	Correct invalid request fields, quantities or template geometry
`401`	Fix the API key or authorization header
`402`	Check the account’s output allowance or active plan
`404` on submission	Check the template ID and owning account
`422` on submission	Repair an invalid saved template before another job
`429`	Wait for the response’s `Retry-After` interval
`404` on status check	Investigate a missing or expired job; do not recreate it automatically
Job status `failed`	Inspect the returned error and correct the cause

Other infrastructure errors can occur outside this documented table. A proxy rejecting a large body, for example, is not evidence that the API accepted a job. Preserve the response and investigate the request stage.

Distinguish terminal states from temporary waits

POST /print → 202 + jobId → save jobId
                           ↓
                      GET /print/{jobId}
                        pending / processing → wait, then check again
                        completed → download URL
                        failed → stop and investigate

Stop on unrecognized states as well as failed. A client that interprets every unfamiliar response as “still processing” can wait indefinitely.

Our downloadable clients use a two-minute polling window, a two-second normal interval and a timeout on each HTTP request. A request already in progress can extend beyond the polling window by its request timeout; this is a client policy, not a server completion guarantee.

Resume a job without creating another one

The clients save a small job file next to the intended PDF. For an output called labels.pdf, resume with:

node labels.mjs resume labels.pdf.job.json labels.pdf
# Python alternative:
# python3 labels.py resume labels.pdf.job.json labels.pdf

The resume command only checks the saved job and downloads its result. It does not call POST /print.

If the initial POST timed out before a job ID arrived, there may be no job file. Do not treat that as proof of rejection. Record the time, template and intended quantity, and reconcile the uncertain submission before repeating it. The public contract does not specify an idempotency-key header for print submission.

Respect both rate limits

The checked contract limits each key to 120 requests per minute and 1,000 generated labels per minute, with at most 1,000 labels in one print job. Count labels by adding every item’s quantity.

Three records requesting 500 copies each total 1,500 labels. They need more than one job and cannot all be generated inside a single key’s 1,000-label minute. Moving records into separate requests does not remove that per-minute limit.

For 429 during polling, wait for Retry-After before checking the same job. If that wait exceeds your local deadline, stop and resume later. Keep automatic retries off for print submission until your integration explicitly handles rejected and ambiguous requests differently.

Treat a completed URL as delivery

The API reference describes the output URL as temporary, approximately 24 hours. Download the PDF promptly and store an authorized copy if the receiving team needs it later. URL expiry is not a promise about indefinite job availability or a complete data-retention policy.

Send the API key to the API endpoints only. The storage download uses the returned URL without an Authorization header. Avoid putting that signed URL into analytics, screenshots or public issue reports.

A download failure is a reason to recheck the existing job or retry its still-valid file URL. It is not, by itself, a reason to produce another batch.

Give the operator a useful status

Situation	Message and action
Invalid product data	“Correct the selected data before generating labels.”
Waiting for job completion	“Preparing labels. This request has already been submitted.”
Polling stopped	“Check the existing job before starting another batch.”
Completed file downloaded	“PDF ready. Check size and copies before printing.”

Keep the internal request reference, job ID, template ID, quantity, timestamps and sanitized failure category. Those fields let you explain what happened without storing keys or entire upstream records in logs.