Skip to main content

Error codes

DPay Web EID uses standard HTTP status codes together with detailed business error codes in the response body.

Error response format​

Business errors (non-validation 4xx errors)​

{
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable error description."
  }
}

Validation errors (422)​

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

The errors field is a map in which each field name points to a list of validation messages for that field.

Error code table​

HTTPError codeDescriptionSolution
401AUTHENTICATION_REQUIREDMissing Authorization headerAdd Authorization: Bearer <key>
401INVALID_API_KEYInvalid, expired or revoked keyCheck the key in the panel and generate a new one if necessary
401TENANT_NOT_FOUNDNo tenant found for this keyThe key may have been deleted - contact support@dpay.pl
403TENANT_SUSPENDEDTenant account suspendedContact support@dpay.pl
403TRANSACTIONS_NOT_AVAILABLETransactions are unavailable for this session typeTransactions are available only for purpose=account_data
404RESULT_NOT_AVAILABLEVerification result unavailableWait until the session reaches completed, or check whether the session exists
404SESSION_NOT_COMPLETEDSession not completedWait until the session is complete before retrieving transactions
404NOT_FOUNDResource not foundCheck the ID in the URL
409SESSION_ALREADY_TERMINALSession is already in a terminal stateCompleted sessions cannot be cancelled
422INVALID_PURPOSE_MODE_COMBINATIONUnsupported purpose + mode combinationSee the combination table
422(field validation)Request field validation errorCheck errors in the response
429-Request limit exceededWait for the number of seconds specified in the Retry-After header
500-Internal server errorTry again shortly; if the issue persists, contact support

Rate limiting​

Request limits are applied per API key:

  • Default limit: 60 requests per minute per API key

When the limit is exceeded, the server returns 429 Too Many Requests with a Retry-After header that specifies how many seconds to wait.

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

Rate-limiting best practices​

  • Exponential backoff - after a 429 response, wait as instructed by Retry-After, then double the delay (30s → 60s → 120s)
  • Caching - cache responses from GET /verifications/{id} instead of polling in a tight loop
  • Webhooks over polling - use webhooks instead of polling the session status
  • Batch requests - group requests instead of sending many individual ones

Debugging​

Example - purpose/mode combination validation​

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"
  }'

Response:

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

Solution: change purpose to account_data, or change mode to single/sequential/pool.

Example - field validation error​

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

Response:

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

Solution: add the required provider field, or use sequential/pool mode.

Support​

If you encounter an error that is not listed in this table or do not know how to resolve it, email support@dpay.pl and include:

  • The session ID (if applicable)
  • The exact request and response, with the API key removed
  • The timestamp when the error occurred
  • A description of what you were trying to achieve
Last updated on