Errors

The Mural API can throw various errors. If it is expected that an error from the Mural API should be handled gracefully, an error will be serialized to the http response as a MuralServiceException with the following shape:

interface MuralServiceException {
  errorInstanceId: string,
  name: MURAL_ERROR_NAME, // identifier of the specific error type, see below
  message: string
  params: map<string, any> // params defined by the specific error type, see below
}

We have a number of specific MuralServiceException types, which are outlined below:

SignedAgreementRequiredException

Definition

interface SignedAgreementRequiredException extends MuralServiceException {
  name: "SignedAgreementRequiredException",
  message: "End user must accept Terms of Service",
  params: {
    organizationId: string 
  }
}

Expected next steps:

You should generate a new Terms of Service link using the hosted TOS link endpoint and display that to your user such that they can sign the Terms of Service.

PayoutQuoteExpiredException

Definition

interface PayoutQuoteExpiredException extends MuralServiceException {
  name: "PayoutQuoteExpiredException";
  message: "This payout request had an expired quote. The exchange rate has been automatically updated for the effected payouts. Please retry the payout to execute the payout request with the updated payouts.";
  params: {
    expiredQuotes: ExpiredQuote[];
  };
}

interface ExpiredQuote {
  payoutId: string;
  fiatCurrencyCode: string;
  previousRate: number; // represents 1 USD equivalent in the destination currency
  newRate: number; // represents 1 USD equivalent in the destination currency
  previousFiatAmount: number;
  newFiatAmount: number;
}

Expected next steps:

You can immediately turn around and execute the Payout Request again, or you can show this information to your user for them to take the next step.

PayinMinimumNotMetError

Definition:

export class PayinMinimumNotMetError extends MuralServiceException {
  name = 'PayinMinimumNotMetError';
  message: `Payin amount less fees must be greater than ${params.minimumFiatAmount.fiatAmount} ${params.minimumFiatAmount.fiatCurrencyCode}. Net payout amount provided was ${(params.providedFiatAmount.fiatAmount - params.fees.fiatAmount)} ${params.providedFiatAmount.fiatCurrencyCode}`;
  params: {
    minimumFiatAmount: FiatAmount;
    providedFiatAmount: FiatAmount;
    fees: FiatAmount;
    exchangeRate?: number;
  };
}

export class FiatAmount {
  fiatAmount: number;
  fiatCurrencyCode: string;
}

Expected next steps:

You should make a new payin request where the payin amount less fees is greater than the minimum fiat amount.

PayoutMinimumNotMetError

Definition:

export class PayoutMinimumNotMetError extends MuralServiceException {
  name = 'PayoutMinimumNotMetError';
  message: `Payout amount less fees must be greater than ${params.minimumFiatAmount.fiatAmount} ${params.minimumFiatAmount.fiatCurrencyCode}. Net payout amount provided was ${(params.providedFiatAmount.fiatAmount - params.fees.fiatAmount)} ${params.providedFiatAmount.fiatCurrencyCode}`;
  params: {
    minimumFiatAmount: FiatAmount;
    providedFiatAmount: FiatAmount;
    fees: FiatAmount;
    exchangeRate?: number;
  };
}

export class FiatAmount {
  fiatAmount: number;
  fiatCurrencyCode: string;
}

Expected next steps:

You should make a new payout request where the payout amount less fees is greater than the minimum fiat amount.

InsufficientBalanceError

Definition

interface InsufficientBalanceError extends MuralServiceException {
  name: "InsufficientBalanceError";
  message: "Insufficient balance for transaction. Required: {requiredAmount} {availableBalance.tokenSymbol}, Available: {availableBalance.amount} {availableBalance.tokenSymbol}";
  params: {
    requiredAmount: string;
    availableBalance: {
      amount: string;
      tokenSymbol: string;
      blockchain: string;
    }
    payoutId: string;
  };
}

Expected next steps:

This error indicates that the account does not have sufficient token balance to complete the requested transaction. You should either:

Deposit additional funds to the account to meet the required amount
Reduce the transaction amount to be within the available balance
Check that you are using the correct account with sufficient funds

PayoutMethodError

Definition

interface PayoutMethodError extends MuralServiceException {
    name: "PayoutMethodError";
    message: "Payout method {payoutMethodId} is in an error state. Until remediated, any payouts using this payout method will fail. Please use a different payout method or contact support for more information.";
    params: {
      payoutMethodId: string;
      payoutMethodErrorReason: PayoutMethodErrorReason;
    };
  }

  enum PayoutMethodErrorReason {
    DISABLED_BY_PROVIDER = "DISABLED_BY_PROVIDER"
  }

Expected next steps:

This error indicates that the payout method is currently unavailable and cannot be used to process payouts. The payoutMethodErrorReason field explains why:

DISABLED_BY_PROVIDER: The payment provider has deactivated the external account associated with this payout method. This typically occurs when the provider detects an issue with the bank account details or compliance status.

You should either:

Use a different payout method for the recipient
Create a new payout method with updated bank account details
Contact support to understand why the provider disabled the account and what steps are needed to remediate