Kody błędów

DPay Web EID używa standardowych kodów HTTP wraz ze szczegółowymi kodami błędów biznesowych w treści odpowiedzi.

Format odpowiedzi błędów

Błędy biznesowe (4xx bez walidacji)

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Czytelny opis błędu."
  }
}

Błędy walidacji (422)

{
  "message": "The provider field is required.",
  "errors": {
    "provider": ["The provider field is required."]
  }
}

Pole errors to mapa: nazwa pola → lista komunikatów walidacyjnych dla tego pola.

Tabela kodów błędów

HTTP	Kod błędu	Opis	Rozwiązanie
401	AUTHENTICATION_REQUIRED	Brak nagłówka Authorization	Dodaj Authorization: Bearer <klucz>
401	INVALID_API_KEY	Nieprawidłowy, wygasły lub odwołany klucz	Sprawdź klucz w panelu, wygeneruj nowy jeśli trzeba
401	TENANT_NOT_FOUND	Nie znaleziono tenanta dla tego klucza	Klucz mógł zostać usunięty - skontaktuj się z support@dpay.pl
403	TENANT_SUSPENDED	Konto tenanta zawieszone	Skontaktuj się z support@dpay.pl
403	TRANSACTIONS_NOT_AVAILABLE	Transakcje niedostępne dla tego typu sesji	Transakcje dostępne tylko dla purpose=account_data
404	RESULT_NOT_AVAILABLE	Wynik weryfikacji niedostępny	Poczekaj aż sesja przejdzie do completed lub sprawdź czy sesja istnieje
404	SESSION_NOT_COMPLETED	Sesja niezakończona	Poczekaj na zakończenie sesji przed pobieraniem transakcji
404	NOT_FOUND	Zasób nie znaleziony	Sprawdź ID w URL
409	SESSION_ALREADY_TERMINAL	Sesja już w stanie terminalnym	Nie można anulować zakończonych sesji
422	INVALID_PURPOSE_MODE_COMBINATION	Niedozwolona kombinacja purpose + mode	Sprawdź tabelę kombinacji
422	(walidacja pól)	Błąd walidacji pól request	Sprawdź errors w odpowiedzi
429	-	Przekroczono limit zapytań	Odczekaj liczbę sekund z nagłówka Retry-After
500	-	Wewnętrzny błąd serwera	Spróbuj ponownie za chwilę, jeśli problem się powtarza - skontaktuj się z support

Rate limiting

Limity zapytań są stosowane per klucz API:

• Domyślny limit: 60 zapytań/minutę per klucz API

Przy przekroczeniu limitu serwer zwraca 429 Too Many Requests z nagłówkiem Retry-After wskazującym liczbę sekund do odczekania.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 30 seconds."
  }
}

Dobre praktyki rate limiting

• Backoff exponential - przy 429 poczekaj zgodnie z Retry-After, potem podwajaj (30s → 60s → 120s)
• Cache - cache'uj odpowiedzi GET /verifications/{id} - nie pollować w pętli
• Webhooks > polling - używaj webhooków zamiast pollingu statusu sesji
• Batch requests - grupuj zapytania zamiast wysyłać wiele pojedynczych

Debugowanie

Przykład - walidacja kombinacji purpose/mode

curl -X POST https://hub.dpay.pl/api/v1/verifications \
  -H "Authorization: Bearer deid_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "identity_verification",
    "mode": "dynamic",
    "provider": "ais_psd2"
  }'

Odpowiedź:

{
  "error": {
    "code": "INVALID_PURPOSE_MODE_COMBINATION",
    "message": "Purpose 'identity_verification' does not support mode 'dynamic'."
  }
}

Rozwiązanie: zmień purpose na account_data lub mode na single/sequential/pool.

Przykład - błąd walidacji pola

curl -X POST https://hub.dpay.pl/api/v1/verifications \
  -H "Authorization: Bearer deid_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{}'

Odpowiedź:

{
  "message": "The provider field is required.",
  "errors": {
    "provider": ["The provider field is required."]
  }
}

Rozwiązanie: dodaj wymagane pole provider lub użyj trybu sequential/pool.

Wsparcie

Jeśli napotkasz błąd którego nie ma w tej tabeli lub nie wiesz jak go rozwiązać, napisz na support@dpay.pl podając:

• ID sesji (jeśli dotyczy)
• Dokładny request i response (usunięty klucz API)
• Znacznik czasu wystąpienia błędu
• Opis co próbowałeś osiągnąć