Błędy i limity

Paperjoy używa standardowych kodów HTTP. Każdy błąd ma body JSON z polem message. Błędy walidacji mają też obiekt errors z kluczami odpowiadającymi polom. Komunikaty błędów są zawsze po angielsku.

Kody statusów

Kod	Znaczenie	Co zrobić	Ponawiać?
`400`	Brak nagłówka `Idempotency-Key`.	Dodaj klucz.	Po poprawce
`401`	Brak klucza API albo klucz jest błędny, unieważniony lub wygasł.	Sprawdź nagłówek `Authorization` albo utwórz nowy klucz.	Po poprawce
`402`	Tryb live i mniej niż jeden kredyt.	Kup kredyty.	Po poprawce
`403`	Klucz nie ma uprawnienia albo zasób należy do innego konta.	Sprawdź klucz i ID.	Nie
`404`	ID nie istnieje albo należy do drugiego trybu.	Sprawdź ID i użyty klucz.	Nie
`409`	`Idempotency-Key` użyto wcześniej z innym body albo próbowano zmienić, wysłać lub usunąć pocztówkę, która nie jest już szkicem.	Użyj nowego klucza dla zmienionej pocztówki albo sprawdź `status` pocztówki.	Z nowym kluczem
`422`	Pole jest nieprawidłowe albo tekst się nie mieści.	Popraw pola wymienione w `errors`.	Po poprawce
`429`	Przekroczono limit żądań.	Odczekaj i spróbuj ponownie.	Po odczekaniu
`5xx`	Błąd po naszej stronie.	Odczekaj i ponów z wykładniczym opóźnieniem.	Tak

Paperjoy odtwarza tylko udane odpowiedzi. Przez 7 dni ponowienie POST /api/postcards z kluczem, który już utworzył pocztówkę, zwraca pierwotną odpowiedź 201. Odpowiedzi z błędem nie są zapisywane, więc po 402, 422 lub 429 możesz ponowić żądanie z tym samym kluczem, gdy usuniesz przyczynę. 409 oznacza, że klucz utworzył już pocztówkę z innym body; dla zmienionej pocztówki użyj nowego klucza.

Błędy walidacji

{
  "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."
    ]
  }
}

Używaj kluczy z errors, aby wyróżnić pola w swoim interfejsie. Nie porównuj treści komunikatów; mogą się zmienić. Błędy specyficzne dla Paperjoy:

Pole	Komunikat	Rozwiązanie
`content`	The content does not fit on the postcard.	Skróć tekst lub usuń puste linie. Zobacz Treść i wygląd kartki.
`signature`	The signature does not fit on one line of the postcard.	Skróć podpis.
`address`	The sender or recipient address does not fit on the envelope.	Skróć najdłuższą linię adresu. Zobacz Układ koperty.
`draft`	You already have 100 open drafts.	Wyślij lub usuń część szkiców. Zobacz Szkice.
`signature_id`	The selected signature is unavailable or is not active for your plan.	Użyj podpisu `active` z `GET /api/signatures` albo sprawdź swój plan.

Limity

Czego dotyczy	Limit	Wspólny dla
Zamawianie pocztówek (tworzenie bez `draft` albo wysyłka szkicu)	100 na dobę	API, MCP i edytora
Otwarte szkice	100 jednocześnie	API, MCP i edytora
Podglądy	30 na minutę	—
Żądania MCP	120 na minutę	—

Limity liczone są dla konta, osobno dla trybu testowego i live. Po przekroczeniu limitu odczekaj przed ponowieniem, a w zadaniach automatycznych stosuj wykładnicze opóźnienie z losowym rozrzutem. Chcesz wysłać więcej niż 100 kartek dziennie? Napisz do nas przed kampanią.

Pierwsze kroki

Sposoby wysyłki

Pocztówki

Konto

Dokumentacja API

Kody statusów

Błędy walidacji

Limity

​Kody statusów

​Błędy walidacji

​Limity

Kody statusów

Błędy walidacji

Limity