Errors & rate limits

The error shape, every error code, and how to handle rate limits.

Every error the API returns has the same body:

{
  "error": true,
  "code": "invalid_request",
  "message": "limit must be an integer from 1 to 100.",
  "param": "limit",
  "requestId": "FZn-uhymjoEEJow="
}

Field
code	Stable and machine-readable. Match on this.
message	For people. It may be reworded at any time.
param	Only for invalid_request: the parameter at fault.
requestId	Also sent as the x-request-id header. Quote it when you contact support.

Error codes

Status	code	Meaning	What to do
400	invalid_request	A parameter is malformed.	Fix the parameter named in param. Don’t retry unchanged.
401	unauthorized	The secret key is missing, unknown, revoked or expired.	Check the Authorization: Bearer sk_… header and the key in the admin.
403	account_suspended	The account has an unpaid invoice.	Settle it in the Print.App admin.
404	not_found	No such resource in your account.	Another account’s project also answers 404.
404	route_not_found	No such endpoint.	Check the method and path.
500	internal_error	Something failed on our side.	Retry with backoff. If it keeps failing, contact support with the requestId.

New codes may be added. Treat an unknown code by its HTTP status.

A 403 with an HTML page

A 403 whose body is an HTML page, with no code and no requestId, didn’t come from the API. Our firewall stopped the request before it reached the API, because it matched a common attack pattern: for example a path-traversal sequence such as ../ in the URL, or traffic from an IP address on a known-abuse list.

Check the request for anything unusual in its URL or body. If it looks normal, contact support with the time of the request (in UTC) and the IP address it came from, so we can find it.

Rate limits

Requests are rate limited. Past the limit you get 429 Too Many Requests. This response comes from the API gateway itself, so its body is { "message": "Too Many Requests" }, not the error shape above.

Retry 429 and 5xx responses with exponential backoff, for example 1s, 2s, 4s, up to a few attempts. Don’t retry other 4xx responses unchanged.