> Tillcast is live: the API at https://api.tillcast.com/v1 and the dashboard at https://dashboard.tillcast.com. A key prints on real printers, so do not call the API unless asked. A job carries its receipt as "document", an array of blocks (the recommended way), or as "receiptline", ReceiptLine text, exactly one of the two: read https://docs.tillcast.com/create-a-print-job.md and https://docs.tillcast.com/concepts/documents.md before you write a job body. Do not code against what does not exist yet: webhooks, a template language, stored templates (a job has no template field), OAuth connections and connectors for Make, Zapier and n8n, and OAuth sign-in for the MCP server. SDKs for TypeScript (@tillcast/sdk, version 0.2.0 or later for blocks) and Python (tillcast) exist as pre-1.0 versions. To show a receipt in a web page without printing, there are the npm packages @tillcast/preview and @tillcast/html-render (0.x, no API key, no call to Tillcast to draw): read https://docs.tillcast.com/preview-a-receipt.md. The docs are the source of truth: check the index https://docs.tillcast.com/llms.txt and https://docs.tillcast.com/roadmap.md before you code against anything. For clean Markdown of any page, append .md to the page URL. The Tillcast MCP server is live at https://api.tillcast.com/mcp and takes an API key as a bearer token (setup: https://docs.tillcast.com/connect-an-ai-assistant.md). It acts on the live account and its tools print on real paper, so do not connect to it or call its tools unless the owner asked you to. The MCP server at https://docs.tillcast.com/_mcp/server is a different one: it only searches these docs and cannot call the Tillcast API.

# Troubleshooting

> What to check when a Star or an Epson printer does not connect to Tillcast or does not print.

## What Tillcast answers

A printer that is turned away gets a bare answer with no text, so that it tells a stranger nothing. What the printer meets tells you where to look. How fast a printer polls again after a refusal has not been measured on a device.

| What the printer meets | Likely cause                                                                                                                                                                                                                                                                                                     |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HTTP `403`             | The secret is wrong or unknown. Or the host belongs to another customer, for example two setup cards were mixed up. Or the printer is refused because its customer is suspended or its location is paused. Or the address names an allowed device and the printer is not that device, or reports no MAC address. |
| HTTP `404`             | The customer code has a typo, so its check symbol fails. Or the domain is not one Tillcast serves. Or the path has more than one part, a trailing slash or a dot.                                                                                                                                                |
| Name does not resolve  | A typo in the domain.                                                                                                                                                                                                                                                                                            |
| Cannot connect         | The URL starts with `http://`. Or the printer has no network, or its time is wrong, or a firewall blocks outgoing HTTPS.                                                                                                                                                                                         |

A mistyped secret names no printer, so Tillcast cannot store a hint about it. Compare the URL by hand.

## Check in this order

1. **Compare the URL.** Compare the URL in the printer's settings with the URL you were given, character by character. The customer code is the part before `.print.tillcast.com`. The secret is the part after the last `/`. See [Printer URL](/concepts/printer-url).
2. **Open the URL in a browser** on the same network, or on a phone on the same network. The check page tells you whether the form of the URL is right, or whether there is a typo in the customer code or in the secret. It cannot tell whether the secret exists.
3. **Use `https`.** A URL that starts with `http://` fails to connect.
4. **CloudPRNT or Server Direct Print is enabled, the settings are saved and the printer was restarted.** Settings apply only after a restart.
5. **Username and password are empty.**
6. **Date and time are right.** The printer needs the right time to validate the HTTPS certificate.
7. **The network works.** The printer needs outgoing HTTPS and working DNS.
8. **The maker is right.** An Epson added as a Star never shows as connected, and the other way round. `GET /v1/printers/{printer}` shows the `vendor`, and `vendor_source` says where it comes from. A maker that was named (`explicit`) cannot be changed: delete the printer and add it again. A printer added by its paper width reads `star` with `vendor_source` `default` until it first connects, which is not a mistake. If it has connected and still reads so, with `detection` `pending`, delete it and add it again with its maker named.
9. **Ask the organization.** Is the customer suspended or the location paused? See [Suspension and pause](/concepts/suspension). Does the printer's address name an allowed device? See below.
10. **Read the printer's status.** `GET /v1/printers/{printer}`, or the printer's page in the dashboard, shows `never_connected`, `online`, `offline`, `wrong_host`, `mac_mismatch`, `customer_suspended` or `location_suspended`. `wrong_host` means the secret was right and the host was not the printer's. `last_seen_at` shows when the printer last polled.

### The address names an allowed device

When an address names an allowed device, a printer whose MAC address is not that one gets the same bare `403` as a wrong URL. The usual causes are a mistyped MAC, a replaced printer, or a firmware that reports no MAC at all. The status `mac_mismatch` and the `reported_mac` appear only when the refused device reported a MAC, and they can take up to an hour to show. Compare the MAC with the label and the self-test print, then fix the field: `PATCH /v1/printers/{printer}` with the right `allowed_mac`, or with `null` to let any device in. A refused printer is let in about 30 seconds after the change, plus its poll interval. See [Printer URL](/concepts/printer-url#allow-only-one-device-optional).

## The printer connects but does not print

* **Paper out, cover open or a jam.** Check the printer first. A Star reports its condition to Tillcast, and `status_code` in `GET /v1/printers/{printer}` shows it, for example `410 Out of paper` or `420 Cover open`. With its spooler on, an Epson reports nothing after it has accepted a page. Epson lists the spooler per printer, and what the TM-m30III-H reports has not been tried. How a printer treats a waiting job while it has such a condition has not been tested.
* **The job ended as `failed`.** `reason` and `result_code` of the job (`GET /v1/jobs/{job}`) say why. On a Star, `510` or `511` mean the printer cannot handle the data it was given: look at the printer's `profile` first, and try a test print. See [Jobs](/concepts/jobs).
* **The job is `failed` with the reason `result_missing`.** This is an Epson. The page was handed to the printer and no result came back within about two minutes. It does not say whether the page printed: look at the paper before you print again.
* **The job is `failed` with the reason `payload_unavailable`.** Tillcast no longer had the job's bytes when the printer asked for it by name. This happens to a job that was taken and never confirmed, from an hour after its `expires_at`. If `delivered_at` is set, the printer took the job before and may have printed it: look at the paper before you print again. See [Jobs](/concepts/jobs#job-lifetime).
* **The job is `failed` with the reason `rendered_for_other_vendor`.** The printer was added by its paper width, and the page was queued before its first connection, so it was made for a Star. The printer that connected is an Epson. Nothing printed. Send the page again: it is made for the Epson. See [Add a printer by its paper width](/printers/profiles#add-a-printer-by-its-paper-width).
* **A change of the printer is `409 printer_not_identified`.** The printer was added by its paper width and its maker is not known yet. Send the change again after the printer has connected. See [Add a printer by its paper width](/printers/profiles#add-a-printer-by-its-paper-width).
* **A job stays `queued` while the printer is online.** An older job is ahead of it: the oldest is served first. List the waiting jobs with `GET /v1/jobs?printer=prn_...&status=pending`, and cancel what is no longer needed.
* **Letters print as garbage or as `?`.** The profile's character set is not the one you meant. The default Star profile writes the text in UTF-8 mode, which needs no code page. A `cp852` profile, or `print_options.encoding` set to `cp852`, sends code page 852, which has the Polish letters. An Epson profile sends `multilingual` unless `encoding` says another: it selects a code page for each character, and the Swedish and the Polish samples printed correctly with it on an Epson TM-m30III-H, the only model checked. `cp1252` suits Western European text only and loses the Polish letters. `cp852` suits Central European text, such as Polish and Czech, and loses the Swedish letters. A character the set does not have prints as `?`, and the job's `warnings` say where with `character_unmappable`. See [Profiles and print options](/printers/profiles#print-options).
* **Lines are cut off or run over the edge.** The printer is on a wider profile than its paper. Choose the profile of its paper. For an Epson added by its paper width, check its line width on paper with the calibration sheet in the dashboard. See [Set up an Epson printer](/printers/epson-setup#step-4-check-the-line-width).
* **A line or a whole row is missing.** This happens in `receiptline` text, when a character of the ReceiptLine language is used as text. Read the job's `warnings`, and escape your own text. Text in the blocks of a `document` is never markup and needs no escape. See [Receipt documents](/concepts/documents#your-own-text-escape-it).
* **Printing is slow over HTTPS.** On a Star, each download and each confirmation may wait. Set **Encryption Level** to `MEDIUM` in the printer's CloudPRNT settings, then **Save & Restart**. This was seen through a tunnel and not against the production service. See [Set up a Star printer](/printers/star-setup#what-has-been-checked-on-a-device).
* **The job expired.** It was not printed within its lifetime. If its `delivered_at` is `null`, the printer never took it. If `delivered_at` is set, the printer took it and no confirmation came, so look at the paper before you print again. See [Jobs](/concepts/jobs#job-lifetime).
* **A receipt printed twice.** 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. An Epson is not offered a job again. See [Jobs](/concepts/jobs#delivery-and-duplicates).
* **The printer shows `offline`.** It has not polled for about 4 minutes: it is switched off, off the network or asleep, or its polling interval is above 60 seconds. `last_seen_at` says when it last polled, and the status is `online` again at its next poll.