Błędy

Każdy błąd publicznego API ma format RFC 9457 i Content-Type: application/problem+json:

{
  "type": "https://developers.rezeri.com/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "The API key lacks the required scope 'bookings:write'.",
  "code": "insufficient_scope",
  "request_id": "6f1c2a9e0b7d4e8f9a3b5c1d2e4f6a8b"
}

• type — adres opisu błędu w tym katalogu (https://developers.rezeri.com/errors/<code>).
• title — standardowa nazwa statusu HTTP.
• status — kod statusu HTTP.
• detail — opis po angielsku dla człowieka. Może się zmienić, więc nie porównuj go w kodzie.
• code — stały identyfikator błędu. Programuj na podstawie code, nie detail.
• request_id — identyfikator żądania. Podaj go, kontaktując się z pomocą techniczną.
• errors[] (opcjonalnie) — lista błędów pól z kluczami field, code, message.

Przy błędach walidacji (validation_error, unknown_field) errors[].code to typ błędu walidatora (np. missing, string_too_long) — lista tych typów nie jest zamknięta. errors[].message bywa po polsku; opieraj się na field i code.

{
  "type": "https://developers.rezeri.com/errors/client_email_required",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The organization requires the client's email.",
  "code": "client_email_required",
  "request_id": "6f1c2a9e0b7d4e8f9a3b5c1d2e4f6a8b",
  "errors": [
    {
      "field": "client.email",
      "code": "client_email_required",
      "message": "The organization requires the client's email."
    }
  ]
}

Odpowiedź z błędem ma zawsze Cache-Control: no-store, a 401 dodatkowo WWW-Authenticate: Bearer.

Katalog kodów

Status	Kod	Znaczenie
400	bad_request	Żądanie nie mogło zostać przetworzone, np. naruszona reguła biznesowa bez własnego kodu.
401	unauthorized	Uwierzytelnienie nie powiodło się.
401	missing_api_key	Brak klucza API w nagłówku Authorization: Bearer <klucz>.
401	invalid_api_key	Klucz API jest nieprawidłowy albo został unieważniony.
401	wrong_environment	Klucz należy do innego środowiska (np. klucz test użyty na produkcji).
403	forbidden	Brak uprawnień do wykonania operacji.
403	organization_unavailable	Organizacja klucza jest niedostępna (np. konto właściciela jest nieaktywne lub w trakcie usuwania).
403	plan_required	Plan organizacji nie obejmuje dostępu do API.
403	api_not_enabled	Dostęp produkcyjny do API nie jest włączony dla tej organizacji.
403	insufficient_scope	Klucz API nie ma wymaganego scope dla tego endpointu.
403	booking_limit_reached	Organizacja osiągnęła limit rezerwacji swojego planu.
404	not_found	Zasób nie istnieje albo nie należy do organizacji klucza.
405	method_not_allowed	Metoda HTTP nie jest obsługiwana dla tej ścieżki.
409	conflict	Operacja jest sprzeczna z bieżącym stanem zasobu.
409	idempotency_in_progress	Żądanie z tym Idempotency-Key jest wciąż przetwarzane; ponów je za chwilę.
409	idempotency_outcome_unknown	Pierwotne żądanie przerwało się po możliwym utworzeniu rezerwacji; sprawdź GET /v1/bookings przed ponowieniem z nowym kluczem.
409	booking_unavailable	Organizacja nie przyjmuje teraz rezerwacji.
409	slot_unavailable	Wybrany termin nie jest dostępny.
409	not_payable	Rezerwacji nie można teraz opłacić online.
409	awaiting_acceptance	Rezerwacja czeka na akceptację usługodawcy, zanim będzie można ją opłacić.
409	already_paid	Rezerwacja jest już opłacona.
409	not_cancellable	Rezerwacji nie można anulować w jej obecnym stanie.
409	cancellation_window_closed	Rezerwacja już się rozpoczęła, więc nie można jej anulować.
409	webhook_endpoint_limit	Organizacja ma już maksymalną liczbę endpointów webhooków; usuń nieużywany.
409	terms_changed	Warunki rezerwacji zmieniły się od ich pobrania (terms_hash jest nieaktualny); pobierz GET /v1/booking-terms ponownie i pokaż je klientowi.
422	validation_error	Żądanie nie przeszło walidacji; szczegóły są w errors[].
422	unknown_field	Żądanie zawiera pole lub parametr spoza schematu.
422	idempotency_key_required	Brak nagłówka Idempotency-Key albo ma on nieprawidłową długość (1–255 znaków).
422	idempotency_key_reused	Ten Idempotency-Key został już użyty z innym żądaniem.
422	invalid_cursor	Kursor paginacji jest nieprawidłowy albo pochodzi z innej listy.
422	invalid_range	Data to jest wcześniejsza niż from.
422	range_too_large	Zakres dat przekracza dozwolone 31 dni.
422	mode_required	Usługa jest dostępna online i stacjonarnie, więc trzeba podać mode.
422	mode_not_supported	Usługa nie jest dostępna w wybranym trybie (mode).
422	terms_required	Organizacja ma warunki do akceptacji, a w żądaniu brakuje terms_accepted: true albo terms_hash z GET /v1/booking-terms.
422	early_performance_required	Klient musi zażądać rozpoczęcia usługi przed upływem 14 dni na odstąpienie od umowy (early_performance_requested: true).
422	client_email_required	Organizacja wymaga adresu e-mail klienta.
422	client_phone_required	Organizacja wymaga numeru telefonu klienta.
422	return_url_required	Rezerwacja opłacana online wymaga pola return_url.
422	return_url_not_allowed	return_url musi być adresem https w domenie dozwolonej dla klucza API.
422	webhook_url_invalid	Adres endpointu webhooków jest niepoprawny; wymagany pełny adres https.
422	webhook_url_not_allowed	Adres endpointu webhooków nie wskazuje na publiczny adres (adresy prywatne i lokalne są blokowane).
422	webhook_event_not_subscribed	Endpoint nie subskrybuje typu zdarzenia, o który prosisz w POST /v1/webhook-endpoints/{id}/test; dodaj go do events albo wybierz inny typ.
422	webhook_test_booking_missing	Organizacja nie ma jeszcze żadnej rezerwacji, z której zbudować przykładowe zdarzenie; utwórz rezerwację testową albo podaj booking_id.
429	rate_limited	Przekroczono limit żądań; ponów po liczbie sekund z nagłówka Retry-After.
429	client_booking_limit	Za dużo rezerwacji dla tego klienta lub pracownika; ponów później.
500	internal_error	Nieoczekiwany błąd po stronie Rezeri; zgłoś go z request_id.
502	payment_provider_error	Operator płatności nie otworzył sesji płatności; ponów żądanie.
503	idempotency_unavailable	Magazyn idempotencji jest chwilowo niedostępny; ponów żądanie za chwilę.