API error codes

The following table lists descriptions of error codes that may be returned when using Tipalti's API web service. When the API returns an error, it is accompanied by an explanation as to why the error occurred.

error code	status	description
-1	UnknownError	An unknown error has occurred. Please submit a ticket to our Support Team.
0	FeesExceedAmount	Total fees are higher than the payment amount.
1	NewPayee	Payee was created without payment details. Add payment details to continue.
2	ProviderRejectedPOErrorCode	Payment was rejected by the payment provider.
3	NoPM	No payment method was selected for this payment.
4	AddressMissing	Payee address is missing.
5	TaxFormsMissing	Required tax forms were not provided.
6	PMNotSupported	The selected payment method is not supported.
7	NoUpdateSinceLastTransactionFailed	Payment was deferred because a previous payment with the same details was rejected. Update the payment details and submit again.
8	HoldPayments	Payee selected “Hold my payments”, so this payment cannot be sent.
9	MissingRefCode	Ref Code is missing. This field is required.
10	ComplianceReview	Payee is pending compliance review.
11	IdapContainsSpaces	IDAP value cannot contain spaces before or after the value.
12	MissingInfo	Payee selected PayPal but does not have a valid PayPal email address.
13	IdapContainsIllegalCharacters	IDAP value contains invalid characters. Special characters and spaces are not allowed.
14	TaxNumberMissing	Tax ID number is missing.
15	VatNumberMissing	VAT number is missing.
16	TaxFormNotValid	Tax form did not pass validation. Ask the payee to review and upload it again.
17	WithholdingRateLimitReached	{0} has reached the limit defined by the {1} tax treaty. You may need to apply withholding on previous payments made during this tax year totaling USD {2}.
18	IdapMaxLengthExceeded	IDAP value exceeds the maximum length of 64 characters.
19	VatValidationFailed	Payee did not pass VAT validation.
998	CustomFieldValueIsNotUnique	Custom field value must be unique.
999	AmountBelowThreshold	Payment amount is below the minimum allowed amount ({0}{1}).
1000	AmountAboveThreshold	Payment amount exceeds the maximum allowed amount ({0}{1}).
1001	UnknownCountryCode	The country code provided in the call does not comply with ISO 3166 (see Country codes).
1002	CountryNotSupported	The country in the request is not supported (e.g., a blocked OFAC country).
1003	UnknownState	The state code provided in the call does not comply with ISO 3166 (see US state codes).
1004	PayerUnknown	The payer name is unknown in Tipalti.
1005	PayeeUnknown	The payee ID is unknown or the iFrame has not yet been called (i.e., the payee has not logged into the iFrame or Supplier Hub, which invokes the iFrame).
1006	EncryptionKeyFailedValidation	The key has failed validation for the provided parameters (see Use encryption key).
1007	ParameterError	A parameter value is missing or invalid. Please review all values in the call.
1009	StringContainsNonEBCDICCharacters	Address and bank information must contain valid EBCDIC characters Valid EBCDIC values: Letters, numbers and special characters ^[\w\d\/\-\?\:\(\)\.\,\'\+ ]+$"
1010	PreferredEntityIsNotValid	The value entered for the preferred payer entity is invalid (i.e., the payer does not have an entity with that name or the payer does not have a default entity defined). Please contact your Support Team.
1011	InvoiceRefCodeUnknown	The invoice reference code provided in the call does not exist in Tipalti. Please check the value entered. The created invoice doesn't have bill lines created.
1012	InvoiceCannotBeCancelled	The invoice cannot be canceled because it was already paid. You can download a Bill details report or call the GetPayeeInvoiceList API function to confirm the invoice was paid.
1013	UnknownCurrencyCode	The currency code provided in the call does not comply with ISO 4217.
1014	InvalidJson	JSON format is invalid.
1015	InvoiceValidationError	An error occurred that prevented the invoice from being processed. Please check the parameters and associated values to ensure accuracy.
1016	ValidationError	An error occurred that prevented the entire payment batch from being processed (e.g., deferred payment, unpayable payee, etc.).
1018	ValidationWarning	The payment batch can still be processed, but there are some issues of which you need to be aware (e.g., a single payment order could not be paid).
1020	BillsModuleMustBeEnabled	The Bills module must be enabled to update Tipalti with the values you included in the call or to retrieve the information you requested from Tipalti.
1021	StatusUpdateSuccessAndFieldFail	Request processed partially. Status updated successfully, other fields were not updated. Please re-send a request with the other fields.
2001	FileNotFound	The file was not found.
2002	CannotReadFile	The payment file cannot be read. Please submit a ticket to our Support Team.
2003	CannotDeleteFile	Since the payment file has already been processed, it cannot be deleted from the folder.
2004	CannotWriteFile	The report has failed to save to the folder. Please submit a ticket to our Support Team.
3001	PaymentAmountTotalMismatch	The amount in the payment file does not match the amount provided in the API call. Please ensure the values entered in the "Amount" field of the payment file equal the totalAmount entered in the API request.
3002	InvalidPayerIpAddress	The payer IP address is invalid. Ensure the IP address is defined as an allowed IP source.
3003	EnahncedSecurityNotConfigured	Dynamic encryption keys are not supported for the payer. Turn on the feature on the Administration > Integrations > API keys screen of the Tipalti Hub.
3004	SubPayerIsNotFound	The subpayer does not exist in the Tipalti system. Please submit a ticket to our Support Team.
3005	SubPayerDoensNotSupportDynamicKey	Dynamic encryption keys are not supported for the subpayer. Turn on the feature on the Administration > Integrations > API keys screen of the Tipalti Hub.
3006	PayerDoesntSupportInvoiceModule	The action you are trying to perform cannot be completed because the payer does not support the Invoices module. To activate the Invoices module, please contact our Sales Team.
4001	CustomFieldDoesNotExist	The custom field you are trying to update or delete does not exist. Ensure the custom field has been defined in Tipalti by checking the Administration > General > Custom fields screen of the Tipalti Hub (see Manage custom fields).
4002	DuplicateInvoiceRefCode	The invoice reference code must be unique.
4003	PaidOrInProcessInvoiceCannotBeUpdated	Paid or in-process invoices (i.e., invoices in the payment cycle) cannot be updated.
4005	AuthorizationError	An authorization error has occurred (each encryption key has valid authorization levels—for example, you cannot use a read-only key to update information).
4006	InvoiceNotApprovedbyPayee	The invoice has not been approved by the payee. You can send the payee a reminder email.
4007	PaymentAmountCannotBeNegative	The payment amount cannot be a negative number. If you are using the Bills module, please apply vendor credit via the Tipalti Hub or digital bills file.
4008	RequestLimitReached	The maximum request limit is 200 records per API call, as the system can only return a maximum of 200 records at a time. If you need information for more than 200 records, you must call the API multiple times.
5002	RequestDoesNotExist	The system tried to process the request, but the request does not exist.
5003	RequestStillInProgress	The system tried to retrieve a response for the request, but the request is still in progress.
5004	CustomFieldValueIsNotUnique	The custom field type has been defined as "unique text" in Tipalti, yet the value you entered for the custom field is not unique.
5005	BillStatusIsNotSupported	You have entered a bill status that is not supported for the relevant parameter of the API function. Please consult the valid values listed in the "Limitation" column for the API function.
5006	GLAccountAssignedToActiveBill	The GL account has already been assigned to the active bill.
6001	CustomFieldValidationError	The system has failed to validate the custom field update that you requested. Ensure the custom field value corresponds with Tipalti's rules.
7001	GlAccountValidationError	The GL account could not be validated. Ensure the GL account has been defined in Tipalti and is linked to the appropriate payer entity, payee, bill, etc.
7002	APAccountNotFound	The AP account is not associated with the payer entity. Submit a request to our Support Team to ensure AP accounts have been linked to your organization's entities.
8001	PaymentTermNotFound	The payment term included in the call does not exist for the payer/ payee or does not match what is defined for the payer/ payee. Check the payer's payment terms on the Administration > Bill settings > Bill payment settings screen in the Tipalti Hub. Check the payee's payment terms directly on the payee record.
8002	CustomFieldInvalidDateFormat	The date format for the custom field is invalid.
8003	PaymentTermValidationError	The payment term cannot be saved in Tipalti (e.g., the term already exists, the format of the term is incorrect, etc.).
8004	TaxCodeValidationError	The tax code cannot be saved in Tipalti (e.g., the payer entity you are trying to link to the tax code does not exist, etc.).
10001	BelowPersonalThreshold	Payment amount is below the minimum threshold defined by the payee.
10002	BelowPayerThresholdForPM	Payment amount is below the minimum threshold for this payment method.
10003	AmountExceedsPayerMax	Payment amount exceeds the payer account configured limit. Contact Tipalti Support if you need to increase this limit.
10004	AmountExceedsPMMax	Payment amount exceeds the maximum allowed for this payment method. Contact your support team.
10005	DuplicatePayee	Duplicate payee with similar Ref Codes in the payment batch. Make sure Ref Codes are unique.
10006	AccountRequiresFunding	Payer account does not have enough funds.
10007	SupportReviewRequired	This payment requires review by Tipalti Operations.
10008	DuplicateRefCode	Ref Code is not unique and was already used for a previous payment.
10009	RefCodeLengthError	Ref Code exceeds the maximum length of {0} characters.
10010	BadPaymentAmount	Invalid payment amount. Value must be positive and at least 0.01.
10011	ParseError	Line could not be processed. The file contains an invalid value for {column}: {value}.
10012	PendingOFACInfo	Additional payee information is required to complete compliance screening.
10013	PayeeIsBlockedByProvider	Payee is blocked by Tipalti.
10014	IllegalCharacterInRefCode	Ref Code contains invalid characters. Only hyphens and underscores are allowed.
10015	RefCodeShouldNotBeEmpty	Ref Code cannot be empty.
10016	PaymentOrderSubmissionFailed	Payment could not be submitted.
10111	CurrencyIsNotSupportedByTipalti	Currency is not supported by Tipalti.
10112	CurrencyIsNotSupportedByPayer	Currency is not supported by the payer.
10114	PayeeCurrencyIsNotProvided	Payment currency was not selected.
10115	PaypalNotSupportCurrency	Currency is not supported for PayPal payments.
10116	MultiplePayeeWithSameIdap	More than 1 payee has this IDAP in the system. Contact Tipalti Support.
10117	IdapIsNull	IDAP value is missing.
10118	PayerNotSupportsScheduling	Payment scheduling is not supported for this payer. Contact Tipalti Support to enable this feature or remove the scheduled date.
10119	AllowEarlyPayIsTrueWhileScheduledDateNotProvided	Early payment is enabled but no scheduled payment date was provided.
10120	POCurrencyDontMatchToAnyLoanerCurrency	Payment currency does not match any loan provider currency configured for this payer.
10121	PayerNotSupportsEarlyPayment	Early payments are not supported for this payer.
10122	EarlyPaymentCannotBePaidViaChosenPaymentMethod	Early payments cannot be processed with the selected payment method.
10123	PayerTermsOfUseNotApproved	Payer terms of use have not been approved.
10124	TipaltiTermsOfUseNotApproved	Tipalti terms of use have not been accepted.
10125	PayeeIsBlocked	Payee is blocked and cannot receive payments.
10126	FailedFraudReview	Payee did not pass fraud review and is under risk review.
10127	PayeeAccountIsClosed	Payee account is closed.
10128	FailedInternalReviewPayee	Payee did not pass internal review.
10129	FailedInternalReviewPayeeWithHiddenReason	Payee did not pass internal review.
10130	FailedInternalReviewPayer	Payer did not pass internal review.
10131	NoDocsProvided	Required setup documents were not provided.
10132	SetupDocumentsNotUploaded	Required setup documents were not uploaded.
10133	SetupDocumentRejected	The uploaded {0} document was rejected. The payee must upload a new document.
10134	SetupDocumentPendingReview	The {0} document was uploaded by the payee but has not been reviewed yet.
10135	IntercashCurrencyIsNotSupported	Payment currency is not supported by the Intercash account.
10136	NoPhysicalAccountFoundForMoneyTransmiter	No physical account was found for the money transmitter.
10137	NoPhysicalAccountRoutingFoundForMoneyTransmiter	No physical account routing was found for the money transmitter.
10138	NoPaymentRouting	No payment routing was found for this payment.
10139	DueDateTooFar	Scheduled payment date is more than 6 months in the future and cannot be submitted.
10140	PayeeIsSuspended	Payee is suspended and cannot receive payments.
10141	PendingFundingPoManuallyDeferred	Payment was manually deferred due to pending funding for early payments.
10142	UnSupportedCountry	{0} is not supported in {1}.
10143	UnSupportedCurrency	Currency {0} is not supported when using {1}.
10144	TaxDocumentsNotUploaded	Tax documents were not uploaded by the payee.
10145	TaxDocumentRejected	The uploaded tax document was rejected. The payee must upload a new document.
10146	TaxDocumentPendingReview	The payee tax document has not been reviewed yet.
10147	MaxWithholdingTypeInvalidValue	Maximum withholding value is invalid.
10148	InvalidIncomeType	Income type is invalid.
10149	IncomeTypeNotSupportedByPayer	Income type {0} is not mapped to your account. Add it to your account or select a different income type.
101050	NoDefaultIncomeTypeForPayer	No default income type is configured for this account. Contact Tipalti Support.
101051	TaxDocumentManualPendingReview	The payee tax form is pending manual review.
101052	TaxDocumentExplanationRejected	The explanation for the tax document was rejected.
101053	TinValidationNotsupported	TIN validation is not supported. Contact Tipalti Support to enable TIN validation or remove the value.
10154	NoUsCertificateExpired	The “No US activities” certificate has expired.
101060	PayeeReviewPending	Payee record is pending review.
101061	PayeeReviewDeclined	Payee profile was reviewed and declined.
101062	PayeeReviewUpdateRequested	Payee record requires an update.
101063	PendingComplianceReview	Payee is pending compliance review.
101064	NoDocsProvidedForComplianceReview	No documents were provided for compliance review.
101065	BillAmountInvalid	Payment amount must be at least 0.01.
101066	AdditionalWithholdingRateInputInvalid	Additional withholding value is invalid. Use decimal numbers, with or without a percentage sign.
101067	TotalWithholdingRateInvalid	Total withholding must be less than 100% of the payment. For this payment, federal withholding = {0} and {1} withholding = {2}.
101068	FailedCalculatingEarlyPaymentFees	Early payment fees could not be calculated for this payment.
101069	LoanProviderNotFoundForPayer	Loan provider was not found for this payer.
101070	RoutingNotProducedVirtualAccountForLoanProviderPayer	No virtual account was created for the loan provider payer.
101071	CouldNotFindRoutingForLoanProviderPayer	No routing could be found for the loan provider payer.
101072	EarlyPaymentDoesNotHaveOriginalAccountInformation	NetNow payment does not have original account information. The payment order for NetNow cannot be processed.
101073	LoanProviderMissingFunds	Loan provider does not have enough funds for early payments.
101074	OnlyVendorCreditsWereSelected	Only vendor credits were selected for this payee.
101075	BankIsOnInternationalSanctionsList	Bank is on an international sanctions list.
101076	PayeeBlockedByCompliance	Payee is blocked by compliance.
101077	BillIsMarkedAsPotentialDuplicate	Bill is marked as a potential duplicate.
101078	AutoResolvePaymentsCanceledByTipalti	Auto-resolve: payment was canceled by Tipalti.
101079	BillIsMarkedAsHoldPayment	Bill is marked as “Hold payment” by {0} on {1}.
101080	UsSourceInputFormatNotValid	US source value is invalid. Enter a number between 0 and 100.
101081	UsSourceValueCantSetForOtherIncomeType	US-sourced payment value cannot be set for income type “OtherIncome”.
101082	UsSourceSetForPayeeAndPayerWithInvalidTaxSetting	US-sourced payment value cannot be set for this payee because the tax settings or tax forms are not valid.
101083	PayerEntityCountryCantPayToPayeeCountry	This payer entity cannot send payments to the payee country.
101084	PayerEntityDoesNotExist	Payer entity does not exist.
101085	TaxEnabledForDifferentDefaultAndPayingPayerEntity	Tax configuration is inconsistent between the default payer entity and the paying payer entity. Align tax settings or use a single payer entity for this payment.
101086	PayeeVerificationFailed	Payee did not pass verification.