> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paperjoy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and rate limits

> What each error means, which ones to retry, and the limits that apply to your account.

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](https://paperjoy.co/billing). | 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 |

> [!NOTE]
>
> 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

```json theme={null}
{
  "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](https://docs.paperjoy.co/en/postcards/write.md#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](https://docs.paperjoy.co/en/postcards/supported-countries.md#envelope-layout). |
| `draft` | You already have 100 open drafts. | Submit or delete some drafts. See [Drafts](https://docs.paperjoy.co/en/postcards/drafts.md). |
| `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](mailto:norbert@paperjoy.co) before your campaign.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.