Dokumentacja API

Kody błędów API Placenie

Każda odpowiedź błędu REST API ma jeden obiekt blad z polami typ, kod, opis, pole, dokumentacja i zadanie_id. Pole dokumentacja prowadzi dokładnie do opisu kodu na tej stronie.

Postać odpowiedzi

Obsługuj błąd po polu typ, a szczegół czytaj z pola kod. Status HTTP zgadza się z typem, więc klient, który patrzy tylko na status, też zachowa się poprawnie.

{
  "blad": {
    "typ": "dane_nieprawidlowe",
    "kod": "dane_nieprawidlowe",
    "opis": "Popraw pola zapytania.",
    "pole": "kwota",
    "pola": {"kwota": ["Kwota musi wynosić co najmniej 100."]},
    "dokumentacja": "https://placenie.pl/docs/bledy#dane_nieprawidlowe",
    "zadanie_id": "req_..."
  }
}

Wartość zadanie_id jest też w nagłówku X-Request-Id. Podaj ją w wiadomości na kontakt@placenie.pl, a znajdziemy to konkretne zapytanie w logach. Pełny opis operacji i webhooka masz w panelu, w zakładce Integracja i klucze.

Typy błędów

dane_nieprawidlowe: Zapytanie ma złe albo brakujące pola. Popraw je i wyślij ponownie.
uwierzytelnienie: Brak klucza API albo klucz nie działa.
nie_znaleziono: Nie ma takiego zasobu albo adresu.
plan: Operacja wykracza poza plan albo stan konta (nieopłacony plan, limit piaskownicy, waluta).
operator: Sklep nie ma podłączonego operatora płatności albo operator odmówił.
konflikt: Zapytanie koliduje z istniejącym stanem (numer zamówienia, klucz idempotencji).
limit: Przekroczony limit zapytań. Odczekaj tyle sekund, ile podaje nagłówek Retry-After.
zadanie_nieprawidlowe: Zapytanie jest poprawne składniowo, ale nie da się go wykonać w tym kontekście.
blad_serwera: Błąd po naszej stronie. Ponów zapytanie, a jeśli wraca, podaj zadanie_id wsparciu.

Wszystkie kody

Kod	HTTP	Typ	Co znaczy i co zrobić
dane_nieprawidlowe	422	dane_nieprawidlowe	Popraw pola zapytania.
kursor_nieprawidlowy	422	dane_nieprawidlowe	Kursor `po` albo `przed` nie wskazuje transakcji tego klucza.
klucz_idempotencji_nieprawidlowy	400	dane_nieprawidlowe	Nagłówek Idempotency-Key ma od 1 do 255 znaków drukowalnych.
wersja_nieznana	400	zadanie_nieprawidlowe	Nagłówek Placenie-Version wskazuje wersję API, której nie ma.
tylko_piaskownica	400	zadanie_nieprawidlowe	Ta operacja działa tylko kluczem testowym (piaskownica).
metoda_niedozwolona	405	zadanie_nieprawidlowe	Ten adres nie obsługuje tej metody HTTP.
klucz_nieprawidlowy	401	uwierzytelnienie	Brak albo nieprawidłowy klucz API.
brak_uprawnien	403	uwierzytelnienie	Ten klucz nie ma dostępu do tej operacji.
nie_znaleziono	404	nie_znaleziono	Nie ma takiego zasobu dla tego klucza.
trasa_nieznana	404	nie_znaleziono	Nie ma takiego adresu w API.
waluta_poza_planem	422	plan	Ta waluta nie jest w Twoim planie. Wielowalutowość jest w planie Skala.
plan_nieoplacony	402	plan	Klucz produkcyjny działa na opłaconym planie. Uruchom plan w panelu.
sklep_poza_planem	402	plan	Ten sklep jest ponad limit sklepów Twojego planu.
limit_demo	402	plan	Konto bez opłaconego planu ma ograniczoną liczbę transakcji testowych. Uruchom plan, żeby testować dalej.
operator_niepodlaczony	409	operator	Podłącz konto operatora płatności w panelu (Integracja), zanim przyjmiesz prawdziwą płatność.
numer_zamowienia_zajety	409	konflikt	Ten numer zamówienia ma już transakcję z inną kwotą albo walutą.
klucz_idempotencji_uzyty	409	konflikt	Ten Idempotency-Key był już użyty z innym zapytaniem. Nowy klucz dla nowego zapytania.
klucz_idempotencji_w_toku	409	konflikt	Zapytanie z tym Idempotency-Key jest właśnie przetwarzane. Ponów za chwilę.
zwrot_odrzucony	422	zadanie_nieprawidlowe	Zwrot nie został przyjęty.
stan_nieprawidlowy	409	zadanie_nieprawidlowe	Transakcja jest w stanie, który nie pozwala na tę operację.
limit_zapytan	429	limit	Za dużo zapytań. Odczekaj liczbę sekund z nagłówka Retry-After.
blad_serwera	500	blad_serwera	Coś poszło nie tak po naszej stronie. Spróbuj ponownie, a jeśli błąd wraca, podaj zadanie_id wsparciu.