Errors and rate limits

Error shape

Errors return a non-2xx status and {"error": {…}} with code and message. Validation errors add fields, mapping each bad field to what's wrong. Rate limits add retry_after_seconds.

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "invalid",
    "message": "Must be between 1 and 50.",
    "fields": { "copies": "Must be between 1 and 50." }
  }
}

The SDKs turn these into typed errors — ValidationError, PermissionError, OutOfPrintsError, RateLimitError and so on (exceptions in PHP, Error variants in Rust) — carrying the same status, code, message, fields and retry delay. See SDKs.

Error codes

Rate limits

Limits are counted per IP address with a token bucket, so short bursts are fine:

Over a limit you get 429 with a Retry-After header (seconds) and retry_after_seconds in the body.

HTTP/1.1 429 Too Many Requests
Retry-After: 3

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Slow down.",
    "retry_after_seconds": 3
  }
}

Retrying safely

The SDKs do this for you: network errors, 429 and 502/503/504 are retried with back-off, waiting as long as Retry-After asks. Every print carries an idempotency key — yours, or one the SDK generates — so a retry after a timeout can never print twice. Pass your own (an order number) to make your own retries safe too. Other 4xx errors (including 410 content_deleted) are not retried — fix the request instead.

import { CatzPrintError, RateLimitError, ValidationError } from "@catzprint/sdk";

try {
  await cz.printReceipt(commands, { role: "receipt", idempotencyKey: `order-${order.id}` });
} catch (err) {
  if (err instanceof ValidationError) console.error(err.fields); // fix the request
  else if (err instanceof RateLimitError) console.error(`still limited; retry in ${err.retryAfter}s`);
  else if (err instanceof CatzPrintError) console.error(err.status, err.code, err.message);
  else throw err;
}