Pay distribution errors

Learn about errors that may occur during the pay distribution update flow.

This page provides common causes and troubleshooting suggestions for errors that may occur during the pay distribution update flow.

Error codes are returned as part of the accounts object. When there is an error in the pay distribution update flow:


📘

Some error messages shown to the user have placeholders for [Link item name] and [Company name]. In such cases, for the screens samples below, they were replaced by Starbox and GoodLoans, respectively.


{
  "id": "ac81e2bc-2157-4535-8ca4-fb1f068df1fc",
  ...
  "connection": {
    "status": "connected",
    "error_code": null,
    "error_message": null,
    "updated_at": "2019-11-29T08:37:42.112859"
  },
  "pay_distribution": {
    "status": "error",
    "error": "invalid_mfa",
    "error_message": "This user did not provide the correct multi-factor authentication response.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

confirmation_timeout

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

This user did not finish setting up their new pay distribution.

Message to the users

You haven't finished confirming pay distribution. Please try again.

Common causes

The user did not confirm the suggested pay distribution within the given time period.

Troubleshooting steps

  1. Advise the users to confirm their suggested pay distribution again later.
  2. Check with the users if they had any issues while entering the pay distribution details.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "confirmation_timeout",
    "error_message": "This user did not finish setting up their new pay distribution.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

incompatible_config

API error_message

The pay allocation details that have been submitted are not supported by this user's employment account.

Message to the users

Your employment account does not currently support pay allocation updates.

Common causes

Although the platforms define specifications parameters as default (such as min_allocation), they can set a different specification for a particular user. In this case, the pay distribution information submitted is compatible with the general specification but not with the custom specification on this user's account.

Troubleshooting steps

  • No action.
  • As a possible workaround, advise the platform to adapt their pd_config for this particular user to be compatible with their employment account's custom pay distribution parameters.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "incompatible_config",
    "error_message": "The pay allocation details that have been submitted are not supported by this user's employment account.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

account_disconnected

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

This user's connection has expired and requires re-authentication.

Message to the users

Pay allocation updates are not available because your employment account was disconnected. Please log in again.

Common causes

The platform has disconnected a previously connected account. This may happen when a user changes the employment account credentials. Some platforms have short-living sessions and require users to re-authenticate more often.

Troubleshooting steps

Advise the user to try connecting their account again.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "account_disconnected",
    "error_message": "This user's connection has expired and requires re-authentication.",
    "updated_at": "2022-03-29T08:37:42.164522Z"
  }
  ...
}

invalid_account_state

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

This user’s account connection failed, therefore pay distribution could not be updated.

Message to the users

Pay allocation updates are not available because your account connection failed. Please log in to $partner and make sure your account is active, you've accepted terms of service, and your onboarding is complete.

Common causes

Pay allocation updates are not available because user’s account connection has failed.

Troubleshooting steps

Check the account connection error for this account and advise the user to follow the instructions related to that specific error.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "invalid_account_state",
    "error_message": "This user’s account connection failed, therefore pay distribution could not be updated.",
    "updated_at": "2022-03-29T08:37:42.164522Z"
  }
  ...
}

invalid_mfa

API error_message

This user did not provide the correct multi-factor authentication response.

Message to the users

The code you've entered is incorrect.

Common causes

This user did not provide the correct multi-factor authentication (MFA) response that was requested by the platform (for example, SMS code, click on link in email, etc.)

Troubleshooting steps

  1. Advise the users to check if they are able to log in directly to the platform's website or app.
  2. Check with the users if they have received the MFA request.
  3. Check with the users if they are using the correct MFA device.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "invalid_mfa",
    "error_message": "This user did not provide the correct multi-factor authentication response.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

mfa_exhausted

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

This user failed multi-factor authentication too many times, requiring them to re-authenticate.

Message to the users

Unavailable because of too many failed multi-factor authentication attempts. [Link item name] requires you to log in again.

Common causes

The platform temporarily disabled pay distribution update attempts for this employment account due to entering invalid MFA too many times.

Troubleshooting steps

Advise the user to wait a few hours and then attempt updating pay distribution again.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "mfa_exhausted",
    "error_message": "This user failed multi-factor authentication too many times, requiring them to re-authenticate.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

mfa_not_configured

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

This user has not configured multi-factor authentication for their employment account, restricting access to the user's employment data.

Message to the users

Please log in to [Link item name] and configure multi-factor authentication to continue sharing your data with [Company name].

Common causes

The platform does not allow to access the employment data of this account as it does not have a mandatory multi-factor authentication set up.

Troubleshooting steps

Advise the user to configure a multi-factor authentication method on their employment platform and attempt pay distribution update again.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "mfa_not_configured",
    "error_message": "This user has not configured multi-factor authentication for their employment account, restricting access to the user's employment data.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

mfa_timeout

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

This user did not complete multi-factor authentication.

Message to the users

Your multi-factor authentication (MFA) session has expired. Please log in again to complete the MFA process.

Common causes

The user did not submit the requested MFA response necessary to complete their pay distribution update within the given time period.

Troubleshooting steps

  1. Confirm that the user has received the MFA request.
  2. Have the user check if the information for their MFA device or phone number is correct.
  3. Have the user confirm that they are able to log in directly via the platform's website or app.
  4. In the case of an SMS or Voice MFA, advise the user to make sure they are able to receive messages from the platform. If there is an issue, contact the platform's support.
  5. Advise the user to attempt the account connection again.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "mfa_timeout",
    "error_message": "This user did not complete multi-factor authentication.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

mfa_attempts_exceeded

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

This user failed multi-factor authentication too many times, causing them to be unable to attempt further logins until multi-factor authentication method is reset.

Message to the users

Unavailable because of too many unsuccessful multi-factor authentication attempts. Please log in to $partner and reset your multi-factor authentication method.

Common causes

The platform permanently disabled login attempts for this employment account because the user entered invalid MFA too many times. This issue can only be resolved by the user resetting MFA directly on their employment platform.

Troubleshooting steps

  1. Check if the user is able to log in directly via the platform's website or app.
  2. Advise the user to reset their MFA method on platform's website or app.
  3. Advise the user to attempt updating pay distribution again using the new MFA.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "mfa_attempts_exceeded",
    "error_message": "This user failed multi-factor authentication too many times, causing them to be unable to attempt further logins until multi-factor authentication method is reset.",
    "updated_at": "2022-03-29T08:37:42.164522Z"
  }
  ...
}

missing_allocation

📘

This errors triggers the accounts.pay_distribution_failed webhook.

API error_message

This user’s employment account does not have any allocation set up which is required to allocate the remainder.

Message to the users

Please log in to $partner system and set up at least one other pay allocation in your account and then try again.

Common causes

The user has either no editable pay allocations set up or no pay allocations set up at all, but the pay distribution config has minimum or maximum bounds set. There must be at least one other pay allocation to allocate the remainder before adding a constrained pay allocation.

Troubleshooting steps

  • Advise the user to set up a pay allocation in their employment account and then attempt to update their pay distribution again.
  • Alternatively, allow the user to deposit their full paycheck by initializing link without any minimum or maximum bounds in the pay distribution config.
{
  ...
  "connection": {
    "status": "error",
    "error_code": "missing_allocation",
    "error_message": "This user’s employment account does not have any allocation set up which is required to allocate the remainder.",
    "updated_at": "2021-08-29T08:37:42.164522Z"
  }
  ...
}

missing_allocation_type

API error_message

One or more of this account's pay allocations is missing a type (percent/amount/remainder), causing Argyle to be unable to update the user's pay distribution information.

Message to the users

Your employment account does not currently support pay allocation updates.

Common causes

Argyle is not able to perform the pay distribution update because the allocation type (percent/amount/remainder) is missing.

Troubleshooting steps

Advise the user to contact their employer for further clarification.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "missing_allocation_type",
    "error_message": "One or more of this account's pay allocations is missing a type (percent/amount/remainder), causing Argyle to be unable to update the user's pay distribution information.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

not_supported

API error_message

This user's employment account does not support updating pay distribution information.

Message to the users

Your employment account does not currently support pay allocation updates.

Common causes

Argyle is not able to perform the pay distribution because the user's employment account does not support pay distributions.

Troubleshooting steps

  • No action, as pay distribution update on the platform is not possible.
  • As a possible workaround, advise the users to confirm if the pay distribution update is available on the platform. If not, check if the platform can enable it.
If enabled, users can attempt to complete their pay distribution update again. However, even if the pay distribution update becomes enabled, there is no guarantee of a successful update.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "not_supported",
    "error_message": "This user's employment account does not support updating pay distribution information.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

not_supported_by_employer

API error_message

This user's employment account does not support changes to pay distribution information. This may be because the employer has disabled users from editing this information.

Message to the user

Your employment account does not currently support pay allocation updates.

Common causes

Argyle is not able to perform the pay distribution because changes to pay distribution are not supported by the platform — possibly because the employer disabled the editing of this information.

Troubleshooting steps

  • No action, as pay distribution update on the platform is not possible.
  • As a possible workaround, advise the users to confirm if the pay distribution update is available on the platform. If not, check if the platform can enable it.
After enabled, the users can attempt to complete their pay distribution update again. However, even if the pay distribution update becomes enabled, there is no guarantee of a successful update.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "not_supported_by_employer",
    "error_message": "This user's employment account does not support changes to pay distribution information. This may be because the employer has disabled users from editing this information.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

rejected_bank_account

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

The provided bank account cannot be used for pay distribution update. Please provide a different bank account.

Message to the user

You are unable to use this bank account because [Link item name] system has rejected it. Please reach out to [Company name] for help.

Common causes

The provided bank account details are valid, but the bank denied this update request on behalf of the platform because of security concerns.

Troubleshooting steps

  1. Contact the bank to find out why the bank account was rejected.
  2. Provide a new bank account in the pd_config.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "rejected_bank_account",
    "error_message": "The provided bank account cannot be used for pay distribution update. Please provide a different bank account.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

rejected_routing_number

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

The provided routing number is considered invalid by this user's employment account.

Message to the user

You are unable to use this bank account because $partner system has rejected it. Please reach out to $company for help.

Common causes

The platform rejects the update due to some internal routing number validation.

Troubleshooting steps

  1. Contact the bank to find out why the routing number was rejected.
  2. Provide a new routing number in the pd_config, if possible.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "rejected_routing_number",
    "error_message": "The provided routing number is considered invalid by this user's employment account.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

rejected_microdeposit

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

The microdeposit verification failed because the provided value was rejected by this user’s employment platform.

Message to the user

The microdeposit verification failed because the provided value was rejected by this user’s employment platform.

Common causes

The microdeposit verification failed because the provided value was rejected by this user’s employment platform.

Troubleshooting steps

Adjust the microdeposit verification request for the value to match the amount received from the user’s employment platform.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "rejected_microdeposit",
    "error_message": "The microdeposit verification failed because the provided value was rejected by this user’s employment platform.",
    "updated_at": "2022-03-29T08:37:42.164522Z"
  }
  ...
}

service_unavailable

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

This user's employment platform is experiencing downtime and is currently unable to process updates to pay allocations.

Message to the user

[Link item name] system is currently unavailable. Please try again later.

Common causes

This platform is currently experiencing downtime, pay allocation updates are not available at this time.

Troubleshooting steps

  • Have the user to check if they are able to update their pay allocations directly in their employment platform.
  • Advise the user to contact their employer for further clarification.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "service_unavailable",
    "error_message": "This user's employment platform is experiencing downtime and is currently unable to process updates to pay allocations.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

system_error

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

Argyle encountered a problem when reading or updating pay distribution information. Our team has been notified and is investigating.

Message to the user

We've encountered an unexpected error. Please try again later.

Common causes

Something unexpected happened when trying to update bank account pay distribution.

Troubleshooting steps

No action needed. Someone from Argyle is checking what happened. Please contact our support team for more details.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "system_error",
    "error_message": "Argyle encountered a problem when reading or updating pay distribution information. Our team has been notified and is investigating.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

unsupported_allocation_type

API error_message

One or more of this account's pay allocations is not currently supported, causing Argyle to be unable to update the user's pay distribution information. Supported allocation types are percent, amount and remainder.

Message to the user

Your employment account does not currently support pay allocation updates.

Common causes

The allocation type read by the scanner is not one of the allocation types we currently support (percentage allocation and amount allocation).

Troubleshooting steps

No action.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "unsupported_allocation_type",
    "error_message": "One or more of this account's pay allocations is not currently supported, causing Argyle to be unable to update the user's pay distribution information. Supported allocation types are percent, amount and remainder.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

unsupported_bank_accounts

API error_message

This user's employment account includes pay allocations to bank account types that Argyle does not yet support, like HSAs.

Message to the user

Your employment account does not currently support pay allocation updates.

Common causes

Argyle only supports updating pay allocations that have checking or savings bank account types associated with them.

Troubleshooting steps

Advise the user to contact their employer for further clarification.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "unsupported_bank_accounts",
    "error_message": "This user's employment account includes pay allocations to bank account types that Argyle does not yet support, like HSAs.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

unsupported_bank_account_country

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

This user's employment account includes pay allocations to bank accounts of countries that Argyle does not yet support.

Message to the user

Your employment account does not currently support pay allocation updates.

Common causes

This user's employment account includes pay allocations to bank accounts of countries that Argyle does not yet support.

Troubleshooting steps

Advise the user to manually remove the existing pay allocation to a bank account linked to a country that Argyle does not yet support and then attempt to connect an account again.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "unsupported_bank_account_country",
    "error_message": "This user's employment account includes pay allocations to bank accounts of countries that Argyle does not yet support.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

unsupported_mfa_method

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

This user's employment account uses a multi-factor authentication method that Argyle does not currently support.

Message to the user

We were not able to connect your employment account. Please log in to $partner to update your multi-factor authentication method and try again.

Common causes

The user's employment account uses an MFA method currently not supported by Argyle.

Troubleshooting steps

Advise the user to disable or change the MFA method.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "unsupported_mfa_method",
    "error_message": "This user's employment account uses a multi-factor authentication method that Argyle does not currently support.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

physical_mfa_unsupported

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

This user's employment account uses a physical multi-factor authentication method that Argyle does not currently support.

Message to the user

Please log in to $partner system and disable the physical multi-factor authentication method (e.g. USB). Then set up another multi-factor authentication method and try again.

Common causes

The user attempted to use a physical multi-factor authentication method that Argyle does not support.

Troubleshooting steps

The user should disable the physical multi-factor authentication method, then set up an alternative multi-factor authentication method and try again.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "physical_mfa_unsupported",
    "error_message": "This user's employment account uses a physical multi-factor authentication method that Argyle does not currently support.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

waiting_period

📘

This error triggers the accounts.pay_distribution_failed webhook.

API error_message

Pay distribution update is temporarily unavailable. This can happen when an employer requires a waiting period after recent pay distribution updates or after initial account creation.

Message to the user

Your employment account has temporarily disabled pay allocation updates. Please try again later.

Common causes

Pay distribution update was rejected because some employers require a waiting period after recent pay distribution updates or after initial account creation.

Troubleshooting steps

Advise the users to complete their pay distribution update again later.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "waiting_period",
    "error_message": "Pay distribution update is temporarily unavailable. This can happen when an employer requires a waiting period after recent pay distribution updates or after initial account creation.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

card_update_failed

API error_message

Argyle encountered a problem when updating card pay distribution information. Our team has been notified and is investigating.

Message to the user

We've encountered an unexpected error while trying to update your payout cards. Please try again later.

Common causes

Something unexpected happened when trying to update payout cards.

Troubleshooting steps

No action needed. Argyle is investigating what happened. Please contact our support team for more details.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "card_update_failed",
    "error_message": "Argyle encountered a problem when updating card pay distribution information. Our team has been notified and is investigating.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

rejected_card

API error_message

The provided card cannot be used for pay distribution update. Please provide a different card.

Message to the user

You are unable to use this card because $partner system has rejected it. Please reach out to $company for help.

Common causes

Something unexpected happened when trying to add payout cards.

Troubleshooting steps

  1. The user can contact the $company to find out why the card was rejected.
  2. You can provide a new payout card in the pd_config.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "rejected_card",
    "error_message": "The provided card cannot be used for pay distribution update. Please provide a different card.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

bank_and_card_update_failed

API error_message

Argyle encountered a problem when updating bank account and card pay distribution information. Our team has been notified and is investigating.

Message to the user

We've encountered an unexpected error while trying to update your payout cards. Please try again later.

Common causes

Something unexpected happened when trying to update bank account and payout card pay distribution.

Troubleshooting steps

No action needed. Argyle is investigating what happened. Please contact our support team for more details.
{
  ...
  "pay_distribution": {
    "status": "error",
    "error": "bank_and_card_update_failed",
    "error_message": "Argyle encountered a problem when updating bank account and card pay distribution information. Our team has been notified and is investigating.",
    "updated_at": "2019-11-29T08:37:42.164522Z"
  }
  ...
}

Did this page help you?