> 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.

# Errors

> How the Tillcast API reports errors, with status codes, error codes and request ids.

## Error shape

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

```json wordWrap
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such printer.",
    "param": null,
    "request_id": "req_01M466JX008T2V5X7Z9C1E3G5H"
  }
}
```

| Field        | Meaning                                                                                                                                                                                                                                                              |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`       | The kind of error: `invalid_request_error`, `authentication_error`, `permission_error`, `conflict_error`, `idempotency_error`, `rate_limit_error` or `api_error`.                                                                                                    |
| `code`       | A 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.                                                                                                                    |
| `message`    | A sentence for a person. Do not parse it. A message about a document never holds a part of the document.                                                                                                                                                             |
| `param`      | The 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_id` | `req_` 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](mailto:contact@tillcast.com). |

Branch on `code`. Do not parse `message`. The contract in the [API reference](/api-reference) lists the codes of each operation.

## Status codes

| Status       | Meaning                                                                                                                                                                                                                |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`        | The request is malformed or a field is invalid, missing or unknown, for example `invalid_cursor`.                                                                                                                      |
| `401`        | The key is missing, wrong, revoked or expired.                                                                                                                                                                         |
| `403`        | The key is valid but lacks the scope for this call, or the action is not allowed, for example a write by a suspended organization.                                                                                     |
| `404`        | The object does not exist, or belongs to another organization. Tillcast never answers "forbidden" for another organization's object.                                                                                   |
| `405`        | The path exists and the method does not.                                                                                                                                                                               |
| `409`        | A 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. |
| `413`        | The request, the document or what it renders to is too large.                                                                                                                                                          |
| `415`        | The body is not sent as `application/json`.                                                                                                                                                                            |
| `422`        | The 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.                                                   |
| `429`        | The 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](/api/rate-limits).                                                   |
| `500`, `503` | A problem on Tillcast's side. Retry with an idempotency key. See [Status and incidents](/status).                                                                                                                      |

## Codes

| Status       | Codes                                                                                                                                                                                                                                  |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`        | `parameter_invalid`, `parameter_missing`, `parameter_unknown` (the field is in `param`), `invalid_json`, `invalid_query`, `invalid_cursor`, `api_version_unsupported`, `idempotency_key_invalid`                                       |
| `401`        | `authentication_required`, `invalid_api_key`                                                                                                                                                                                           |
| `403`        | `insufficient_scope`, `organization_not_active`, `organization_suspended`, `restricted_key`, `origin_not_allowed`                                                                                                                      |
| `404`        | `resource_missing`, `route_not_found`                                                                                                                                                                                                  |
| `405`        | `method_not_allowed`                                                                                                                                                                                                                   |
| `409`        | `parent_not_active`, `customer_suspended`, `location_suspended`, `not_empty`, `pending_jobs`, `job_not_cancellable`, `already_exists`, `printer_not_identified`                                                                        |
| `413`        | `document_too_large`, `request_too_large`, `rendered_too_large`                                                                                                                                                                        |
| `415`        | `unsupported_media_type`                                                                                                                                                                                                               |
| `422`        | `idempotency_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` |
| `429`        | `queue_full`, `rate_limited`                                                                                                                                                                                                           |
| `500`, `503` | `internal_error`, `printer_domain_unavailable`                                                                                                                                                                                         |

The ones you meet most often:

| Code                                                                                                | When                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameter_unknown`                                                                                 | The 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_query`                                                                                     | Declared 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_exists`                                                                                    | The 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](/api/idempotency).                                                                                                                                                                                           |
| `parameter_invalid`                                                                                 | A 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_scope`                                                                                | The key lacks the scope of the call. It is answered before anything is looked up.                                                                                                                                                                                                                                                                                                                   |
| `resource_missing`                                                                                  | No 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_suspended`                                                          | The customer or location is paused, so no job can be queued. See [Suspension and pause](/concepts/suspension).                                                                                                                                                                                                                                                                                      |
| `pending_jobs`                                                                                      | You moved a printer that has jobs waiting. Send `cancel_pending_jobs: true`, or wait.                                                                                                                                                                                                                                                                                                               |
| `job_not_cancellable`                                                                               | The printer has taken the job, or it has ended.                                                                                                                                                                                                                                                                                                                                                     |
| `printer_not_identified`                                                                            | A 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](/printers/profiles#add-a-printer-by-its-paper-width).                                                                                      |
| `idempotency_key_reused`                                                                            | The `Idempotency-Key` was used with a different request. See [Idempotency](/api/idempotency).                                                                                                                                                                                                                                                                                                       |
| `document_invalid`                                                                                  | A 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](/concepts/documents#errors-in-a-document).                                                                                                                                         |
| `document_empty`, `document_too_large`, `rendered_too_large`, `request_too_large`, `render_timeout` | The document is blank or prints nothing, or it is too large or too slow to render. See [Receipt documents](/concepts/documents#limits-and-refusals).                                                                                                                                                                                                                                                |
| `document_command_not_allowed`                                                                      | The 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_invalid`    | The `profile` or `print_options` of a printer were refused. See [Profiles and print options](/printers/profiles).                                                                                                                                                                                                                                                                                   |
| `profile_mismatch`                                                                                  | The 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_full`                                                                                        | The printer already has 50 jobs waiting.                                                                                                                                                                                                                                                                                                                                                            |
| `rate_limited`                                                                                      | Too many test prints for one printer.                                                                                                                                                                                                                                                                                                                                                               |
| `printer_domain_unavailable`                                                                        | No printer domain is active, so a printer URL cannot be made. Try again later.                                                                                                                                                                                                                                                                                                                      |
| `internal_error`                                                                                    | Something 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 answer                                                          | Retry?                                                         | Same key        | Wait                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------- | -------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No answer: a timeout, a dropped connection, a refused connection    | Yes, the call may have worked                                  | Yes             | Growing waits, such as 1, 2 and 4 seconds, then stop and tell a person                                                                                                                                                                          |
| `408`, `500`, `502`, `503`, `504`                                   | Yes                                                            | Yes             | Growing waits                                                                                                                                                                                                                                   |
| `429 rate_limited`                                                  | Yes                                                            | Yes             | The seconds in `Retry-After`                                                                                                                                                                                                                    |
| `429 queue_full`                                                    | Not in a loop                                                  | Yes             | The 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_active` | No, until the customer or location is reactivated              | Yes, after that | Until someone reactivates it                                                                                                                                                                                                                    |
| `409 already_exists`                                                | Yes, once or twice                                             | Yes             | A moment. The message says "Retry the request"                                                                                                                                                                                                  |
| `409 job_not_cancellable`, `pending_jobs`, `not_empty`              | No: read the object and decide                                 | Not applicable  | Not applicable                                                                                                                                                                                                                                  |
| `409 printer_not_identified`                                        | Not yet: send the change again after the printer has connected | Not applicable  | Until the printer's first connection                                                                                                                                                                                                            |
| `400`, `401`, `403`, `404`, `413`, `415`, `422`                     | No: the request is wrong, or the key is                        | Not applicable  | Fix 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](/create-a-print-job#retry-safely): they never retry a timeout or a dropped connection, so that row is yours.

#### Retry a 5xx or a network error

Retry with the same `Idempotency-Key` and the same body, with growing waits between attempts. See [Idempotency](/api/idempotency).

#### Retry a 429

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`.

#### Do not retry other 4xx unchanged

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.