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 user,
• a Type to automatically handle specific classes of errors/warnings (e.g. translated messages),
• a IsUserActionRequired information for errors/warnings that cannot be resolved without user intervention
• and a 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, a 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 user to handle error based on Type.
true	false	Inform 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
}

If IsUserActionRequired is true, a 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 when we add functionality 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
Throttling	Operation was throttled by the PSP	x	x	DataImport
UnknownFailure	Unknown error/failure. Check Message.	x	x	All

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.