Errors and Warnings

The PayData API uses a unified format for returning errors and warnings.

Resources in PayData have a list of errors and warnings, to get detailed insights into the state of a resource (e.g. account) or status of an operation (e.g. data import).

The format contains

a message with a description of the error/warning which can be displayed to the end user,
a type to automatically handle specific classes of errors/warnings (e.g. translated messages),
an isUserActionRequired flag that's set for errors/warnings that cannot be resolved without end user intervention
and an isTemporary flag that specifies if the error is temporary and will go away.

Errors

Errors contain information about why something is not working or why it has failed.

{
    "message": "Credentials expired 2024-09-01",
    "type": "CredentialsExpiration",
    "isUserActionRequired": true,
    "isTemporary": false
}

If isUserActionRequired is true, the end user is responsible for correcting the error (e.g. update account credentials). If isTemporary is true, the error is expected to go away on its own. Common cases are temporary errors with a PSP that cause a data import to fail. In the case where both are false the error should be investigated.

The following table contains the possible values and the recommended actions.

`isTemporary`	`isUserActionRequired`	Recommended Action
`false`	`false`	Mark resource/operation as erroneous. Display `Message` or custom message based on `Type`. Investigate error.
`false`	`true`	Mark resource/operation as erroneous. Display `Message` or custom message based on `Type`. Request end user to handle error based on `Type`.
`true`	`false`	Inform end user about temporary error. Display `Message` or custom message based on `Type`
`true`	`true`	Display `Message` or custom message based on `Type` This case should not happen.

While uncommon, it is possible that resources have multiple errors at the same time. For example importing a report can fail because it contains unknown transactions and the sum of the transactions does not match the payout amount.

Warnings

A warning informs about potential issues or about something that will lead to an error if not handled. Some actions in PayData (e.g account creation) allow possible errors to be ignored. In this case the error is demoted to a warning.

{
    "message": "Credentials are expiring on 2024-09-01",
    "type": "CredentialsExpiration",
    "isUserActionRequired": true,
    "isTemporary": false
}

If isUserActionRequired is true, the end user is responsible for correcting the error (e.g. update account credentials).

It is possible for resources to have multiple warnings at the same time. For example the account credentials might be expiring soon and the current credentials don't contain all required permissions. The latter can be a warning as PayData might need more permissions once new functionality is added at a later date.

Types

Types are used to categorize errors and warnings so they can be handled in a unified way without interpreting the unstructured Message field.

Type	Description	Warning	Error	Resources
Credentials	Some issue with the credentials. Check `Message`.	x	x	Account
CredentialsExpiration	Credentials are expiring or are expired.	x	x	Account
CredentialsFailure	Credentials are invalid.	-	x	Account
CredentialsPermissionFailure	Credentials have insufficient permissions.	x	x	Account
DataInconsistency	Data received from the provider is inconsistent.	x	x	Report, AccountType
ImportFailure	General data import failure.	x	x	Account, Report, DataImport, AccountType
ImportSuspension	Data imports are suspended until the error is resolved.	-	x	Account
LoginFailure	Authentication with the provider is not possible.	-	x	AccountType
ReportDownloadFailure	Downloading the report failed.	-	x	Report
ReportParseFailure	Parsing the report failed.	-	x	Report
ReportSkip	Report was skipped because it already exists or other reports with the same contents exist.	x	-	Report
ReportValidationFailure	The report's transactions don't reconcile against its payout amount.	x	x	Report
Throttling	Operation was throttled by the PSP	x	x	DataImport
UnknownFailure	Unknown error/failure. Check `Message`.	x	x	All

See Account Type Errors below for how these types combine into an account type's overall state, and Report Errors and Warnings for the cases specific to report processing.

warning

Errors and warnings depend on PSP behavior and can change without notice. New PSPs and functionality might require new error types. Design your code to handle unknown error types.

Account Type Errors

If an account type's state is Ok and its errors array is empty, interaction with the corresponding payment provider works fine. Otherwise, errors describes current problems connecting to and getting data from the payment provider, using the Type values from the table above.

The table below contains a list of known common cases, and the account-type-level state they combine into.

Account Type State	Error Type	Error Message	Error is Temporary
Maintenance	Maintenance	PSP is down for maintenance.	true
Down	UnknownFailure	PSP API is not reachable or responding unexpectedly.	false
Error	ImportFailure	All imports are failing	false
Error	DataInconsistency	Inconsistencies are detected for all imports.	false
Error	UnknownFailure	Unknown error for all accounts.	false
Degraded	LoginFailure	New authentications with PSP not possible.	false
Degraded	ImportFailure	Some imports are failing. Check data import errors for affected accounts.	false
Degraded	DataInconsistency	Inconsistencies are detected for some imports. Check data import errors for affected accounts.	false
Degraded	UnknownFailure	Unknown errors for some accounts.	false

Report Errors and Warnings

Two error/warning cases are specific to report processing, both around payout validation: PayData sums a report's transactions and fees and compares the total against the report's payout amount.

Case State Example

Case	State	Example
Payout validation failure. PayData will retry the import in case the report gets automatically corrected by the PSP.	`ImportError`	`{ // ... "state": "import_error", "warnings": [], "errors": [ { "message": "Calculated payout amount (123.45 EUR) does not match payout of report (120.45 EUR).", "type": "ReportValidationFailure", "isUserActionRequired": false, "isTemporary": true } ] }`
Payout validation failure, but PayData imported the report anyway because no correction was made.	`Imported`	`{ // ... "state": "imported", "warnings": [ { "message": "Calculated payout amount (123.45 EUR) does not match payout of report (120.45 EUR).", "type": "ReportValidationFailure", "isUserActionRequired": false, "isTemporary": false } ], "errors": [] }`

Payout validation failure. PayData will retry the import in case the report gets automatically corrected by the PSP.

ImportError

{
  // ...
  "state": "import_error",
  "warnings": [],
  "errors": [
    {
      "message": "Calculated payout amount (123.45 EUR) does not match payout of report (120.45 EUR).",
      "type": "ReportValidationFailure",
      "isUserActionRequired": false,
      "isTemporary": true
    }
  ]
}

Payout validation failure, but PayData imported the report anyway because no correction was made.

Imported

{
  // ...
  "state": "imported",
  "warnings": [
    {
      "message": "Calculated payout amount (123.45 EUR) does not match payout of report (120.45 EUR).",
      "type": "ReportValidationFailure",
      "isUserActionRequired": false,
      "isTemporary": false
    }
  ],
  "errors": []
}

Errors​

Warnings​

Types​

Account Type Errors​

Report Errors and Warnings​

Errors

Warnings

Types

Account Type Errors

Report Errors and Warnings