Skip to navigation

Errors

HTTP status codes, error codes and the request id to quote in a support request.
View as Markdown

Error shape

An error has an HTTP status and a JSON body with one object, error. Every field is always there.

{
"error": {
"type": "invalid_request_error",
"code": "resource_missing",
"message": "No such printer.",
"param": null,
"request_id": "req_01M466JX008T2V5X7Z9C1E3G5H"
}
}
FieldMeaning
typeThe kind of error: invalid_request_error, authentication_error, permission_error, conflict_error, idempotency_error, rate_limit_error or api_error.
codeA stable code to branch on. The list below holds the codes known today. A new code can be added, so treat one you do not know by its HTTP status.
messageA sentence for a person. Do not parse it. A message about a document never holds a part of the document.
paramThe request field the error is about, for example receiptline, or the path of a block such as document[3].rows[1][0].size, or null.
request_idreq_ and a ULID. The same value is in the Request-Id header of every response, and in X-Request-Id, the name that some HTTP clients and generated SDKs look for. Quote it when you ask for help: write to contact@tillcast.com.

Branch on code. Do not parse message. The contract in the API reference lists the codes of each operation.

Status codes

StatusMeaning
400The request is malformed or a field is invalid, missing or unknown, for example invalid_cursor.
401The key is missing, wrong, revoked or expired.
403The key is valid but lacks the scope for this call, or the action is not allowed, for example a write by a suspended organization.
404The object does not exist, or belongs to another organization. Tillcast never answers “forbidden” for another organization’s object.
405The path exists and the method does not.
409A conflict with the state of an object, for example cancelling a job that the printer has already downloaded, creating a job for a suspended customer or a paused location, or moving a printer that has jobs waiting.
413The request, the document or what it renders to is too large.
415The body is not sent as application/json.
422The request is understood but refused, for example idempotency_key_reused, a block that cannot be printed as it is said or a document with the command property.
429The printer’s queue is full, or a limit on test prints was reached. A Retry-After header says how long to wait. See Rate limits and retention.
500, 503A problem on Tillcast’s side. Retry with an idempotency key. See Status and incidents.

Codes

StatusCodes
400parameter_invalid, parameter_missing, parameter_unknown (the field is in param), invalid_json, invalid_query, invalid_cursor, api_version_unsupported, idempotency_key_invalid
401authentication_required, invalid_api_key
403insufficient_scope, organization_not_active, organization_suspended, restricted_key, origin_not_allowed
404resource_missing, route_not_found
405method_not_allowed
409parent_not_active, customer_suspended, location_suspended, not_empty, pending_jobs, job_not_cancellable, already_exists, printer_not_identified
413document_too_large, request_too_large, rendered_too_large
415unsupported_media_type
422idempotency_key_reused, document_invalid, document_empty, document_command_not_allowed, render_timeout, profile_mismatch, profile_unknown, profile_not_connectable, profile_vendor_mismatch, print_options_invalid
429queue_full, rate_limited
500, 503internal_error, printer_domain_unavailable

The ones you meet most often:

CodeWhen
parameter_unknownThe body has a field the route does not take. The body is closed. A field that a block of a document does not have is 422 document_invalid instead, with its path in param. Every route also refuses a query parameter it does not take with this code, and param is its name. The check comes before the key is read, so an unknown query parameter without a key is a 400, not a 401.
invalid_queryDeclared for a query string that cannot be read at all. The server does not produce it today: it reads even a malformed query string, and what is wrong comes back as parameter_unknown for a parameter the route does not take and as parameter_invalid for a value that is not allowed, such as status=queued. Handle it like any other 400.
already_existsThe object is there already (a concurrent create). The message says “Retry the request”: send the same request again, with the same Idempotency-Key if it had one. See Idempotency.
parameter_invalidA field has the wrong type or an invalid value, for example document that is an object and not an array of blocks. The message says where the text of the earlier form goes now.
insufficient_scopeThe key lacks the scope of the call. It is answered before anything is looked up.
resource_missingNo such object, another organization’s object, a deleted one, an id that does not parse, or a MAC address where a printer id belongs. All look the same.
customer_suspended, location_suspendedThe customer or location is paused, so no job can be queued. See Suspension and pause.
pending_jobsYou moved a printer that has jobs waiting. Send cancel_pending_jobs: true, or wait.
job_not_cancellableThe printer has taken the job, or it has ended.
printer_not_identifiedA change to the profile, print_options or allowed_mac of a printer, or welcome_print turned on, before the maker of a printer added by its paper width is known. Send it again after the printer has connected. See Profiles and print options.
idempotency_key_reusedThe Idempotency-Key was used with a different request. See Idempotency.
document_invalidA job has both document and receiptline, or neither, or a block cannot be printed as it is said. param is the path of the first problem, such as document[3].rows[1][0].size. See Errors in a document.
document_empty, document_too_large, rendered_too_large, request_too_large, render_timeoutThe document is blank or prints nothing, or it is too large or too slow to render. See Receipt documents.
document_command_not_allowedThe document uses the command property, or a hexadecimal escape that would put a control character into the text. The message gives the line and the column.
profile_unknown, profile_not_connectable, profile_vendor_mismatch, print_options_invalidThe profile or print_options of a printer were refused. See Profiles and print options.
profile_mismatchThe printer reported a model of Star’s Line mode family, and its profile cannot print on it. Star Line printers cannot be used through the API yet.
queue_fullThe printer already has 50 jobs waiting.
rate_limitedToo many test prints for one printer.
printer_domain_unavailableNo printer domain is active, so a printer URL cannot be made. Try again later.
internal_errorSomething failed on Tillcast’s side and nothing was queued. Retry with the same Idempotency-Key, and quote the request id if it persists.

What to do

One table for a client that sends a create call (a job, a printer) and has to decide what to do with the answer. “Same key” means the same Idempotency-Key and the same body: a retry with another body is 422 idempotency_key_reused.

The answerRetry?Same keyWait
No answer: a timeout, a dropped connection, a refused connectionYes, the call may have workedYesGrowing waits, such as 1, 2 and 4 seconds, then stop and tell a person
408, 500, 502, 503, 504YesYesGrowing waits
429 rate_limitedYesYesThe seconds in Retry-After
429 queue_fullNot in a loopYesThe seconds in Retry-After (30 today). The queue empties as the printer prints, as you cancel jobs and as jobs pass their expires_at (24 hours by default), so a printer that is off or out of paper makes no room for hours: tell a person
409 customer_suspended, location_suspended, parent_not_activeNo, until the customer or location is reactivatedYes, after thatUntil someone reactivates it
409 already_existsYes, once or twiceYesA moment. The message says “Retry the request”
409 job_not_cancellable, pending_jobs, not_emptyNo: read the object and decideNot applicableNot applicable
409 printer_not_identifiedNot yet: send the change again after the printer has connectedNot applicableUntil the printer’s first connection
400, 401, 403, 404, 413, 415, 422No: the request is wrong, or the key isNot applicableFix the cause first

A retry of a read (GET) needs no key. The SDKs retry some of these by themselves and not others, see Retry safely: they never retry a timeout or a dropped connection, so that row is yours.

Retry with the same Idempotency-Key and the same body, with growing waits between attempts. See Idempotency.

Wait for the number of seconds in Retry-After, then retry. For queue_full, the queue empties as the printer prints, as you cancel jobs and as jobs pass their expires_at.

A 400, 401, 403, 404, 413 or 422 fails the same way until you fix the request. A 409 fails until the conflict ends, for example when the customer is reactivated. The Python SDK retries a 409 twice on its own, which cannot help for a suspended customer.