Skip to main content

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​

HTTPKod błęduOpisRozwiązanie
401AUTHENTICATION_REQUIREDBrak nagłówka AuthorizationDodaj Authorization: Bearer <klucz>
401INVALID_API_KEYNieprawidłowy, wygasły lub odwołany kluczSprawdź klucz w panelu, wygeneruj nowy jeśli trzeba
401TENANT_NOT_FOUNDNie znaleziono tenanta dla tego kluczaKlucz mógł zostać usunięty - skontaktuj się z support@dpay.pl
403TENANT_SUSPENDEDKonto tenanta zawieszoneSkontaktuj się z support@dpay.pl
403TRANSACTIONS_NOT_AVAILABLETransakcje niedostępne dla tego typu sesjiTransakcje dostępne tylko dla purpose=account_data
404RESULT_NOT_AVAILABLEWynik weryfikacji niedostępnyPoczekaj aż sesja przejdzie do completed lub sprawdź czy sesja istnieje
404SESSION_NOT_COMPLETEDSesja niezakończonaPoczekaj na zakończenie sesji przed pobieraniem transakcji
404NOT_FOUNDZasób nie znalezionySprawdź ID w URL
409SESSION_ALREADY_TERMINALSesja już w stanie terminalnymNie można anulować zakończonych sesji
422INVALID_PURPOSE_MODE_COMBINATIONNiedozwolona kombinacja purpose + modeSprawdź tabelę kombinacji
422(walidacja pól)Błąd walidacji pól requestSprawdź errors w odpowiedzi
429-Przekroczono limit zapytańOdczekaj liczbę sekund z nagłówka Retry-After
500-Wewnętrzny błąd serweraSpró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ąć
Last updated on