Errors and rate limits

Paperjoy uses standard HTTP status codes. Every error has a JSON body with a message. Validation errors also have an errors object keyed by field. Error messages are always in English.

Status codes

Code	Meaning	What to do	Retry?
`400`	`Idempotency-Key` header is missing.	Add a key.	After fixing
`401`	The API key is missing, wrong, revoked, or expired.	Check the `Authorization` header or create a new key.	After fixing
`402`	Live mode and less than one credit.	Buy credits.	After fixing
`403`	The key lacks an ability, or the resource belongs to another account.	Check the key and the ID.	No
`404`	The ID doesn’t exist or belongs to the other mode.	Check the ID and which key you used.	No
`409`	The `Idempotency-Key` was used before with a different body, or you tried to change, submit, or delete a postcard that is no longer a draft.	Use a new key for the changed postcard, or check the postcard’s `status`.	With a new key
`422`	A field is invalid, or the text doesn’t fit.	Fix the fields listed in `errors`.	After fixing
`429`	A rate limit was exceeded.	Wait, then try again.	After waiting
`5xx`	Something failed on our side.	Wait and retry with exponential backoff.	Yes

Paperjoy replays only successful responses. For 7 days, retrying POST /api/postcards with a key that already created a postcard returns the original 201. Error responses are not stored, so after a 402, 422, or 429 you can retry with the same key once you fix the cause. A 409 means the key already created a postcard with a different body; use a new key for the changed postcard.

Validation errors

{
  "message": "The content does not fit on the postcard. Shorten it or remove blank lines.",
  "errors": {
    "content": [
      "The content does not fit on the postcard. Shorten it or remove blank lines."
    ]
  }
}

Use the keys in errors to highlight fields in your UI. Don’t match on the message text; it may change. Errors specific to Paperjoy:

Field	Message	Fix
`content`	The content does not fit on the postcard.	Shorten the text or remove blank lines. See Make it fit.
`signature`	The signature does not fit on one line of the postcard.	Shorten the signature.
`address`	The sender or recipient address does not fit on the envelope.	Shorten the longest address line. See Envelope layout.
`draft`	You already have 100 open drafts.	Submit or delete some drafts. See Drafts.
`signature_id`	The selected signature is unavailable or is not active for your plan.	Use an `active` signature from `GET /api/signatures`, or check your plan.

Rate limits

What	Limit	Shared between
Ordering postcards (creating without `draft`, or submitting a draft)	100 per day	API, MCP, and the editor
Open drafts	100 at a time	API, MCP, and the editor
Previews	30 per minute	—
MCP requests	120 per minute	—

Limits are counted per account and separately for test and live mode. When you hit one, wait before you try again, and back off exponentially with some random jitter in automated jobs. Need to send more than 100 cards a day? Contact us before your campaign.

Get started

Ways to send

Postcards

Account

API reference

Errors and rate limits

Status codes

Validation errors

Rate limits

​Status codes

​Validation errors

​Rate limits

Status codes

Validation errors

Rate limits