error-codes.md

Frontend contract error code reference

This document is the frontend-side reference for Soroban contract errors that the UI maps to user-facing messages. The mapping lives in src/lib/contract/errors.ts and is used by src/hooks/useTransaction.tsx when a transaction fails.

For the contract-side reference in the smart-contract repository, see the upstream error documentation in the ILN Smart Contract repo: https://github.com/Invoice-Liquidity-Network/ILN-Smart-Contract/blob/dev/docs/error-codes.md

Error map

Contract error code	User-facing title	User-facing message	Remediation
InvalidDiscountRate	Invalid Discount Rate	The discount rate must be between 0.01% and 50%.	Adjust the discount rate and try again.
Unauthorized	Unauthorized Action	Your wallet is not authorized to perform this action.	Check if you are using the correct connected wallet account.
InvoiceNotFound	Invoice Not Found	The requested invoice could not be found on the network.	Verify the invoice ID and ensure it was created successfully.
AlreadyFunded	Invoice Already Funded	This invoice has already been funded and cannot be funded again.	Read the invoice status first and stop funding once the invoice is funded.
AlreadyPaid	Invoice Already Paid	This invoice has already been fully paid.	No further action is required for this invoice.
InvoiceAlreadyPaid	Invoice Already Paid	This invoice has already been fully paid.	No further action is required for this invoice.
NotFunded	Invoice Not Funded	This invoice has not been funded yet.	Fund the invoice first, or wait until the correct state transition has occurred.
InvalidAmount	Invalid Amount	The provided amount is not acceptable to the contract.	Send a positive amount that matches the invoice rules and token decimals.
InvalidDueDate	Invalid Due Date	The due date is not valid for invoice creation or update.	Provide a future due date that satisfies the contract validation rules.
InvoiceDefaulted	Invoice Defaulted	This invoice has already defaulted and can no longer be settled normally.	Use the default or appeal flow instead of settlement or funding flows.
NothingToClaim	Nothing To Claim	There is no yield or claimable amount available yet.	Wait until the invoice has generated claimable yield, then retry the claim.
NotYetDefaulted	Invoice Not Yet Defaulted	This invoice has not reached the default threshold yet.	Wait until the invoice is actually defaulted before using the default recovery flow.
OverfundingRejected	Overfunding Rejected	The funding attempt would exceed the invoice remaining amount.	Fund only the remaining unpaid amount, or read the remaining balance first.
InvoiceExpired	Invoice Expired	This invoice has expired and can no longer be processed.	You may need to request a new invoice from the issuer.
BatchTooLarge	Batch Too Large	The submitted batch exceeds the contract maximum batch size.	Split the request into smaller batches and retry.
InvoiceCancelled	Invoice Cancelled	This invoice was cancelled by the issuer.	Please contact the issuer for more details.
AlreadyCancelled	Invoice Already Cancelled	This invoice was already cancelled.	Treat the invoice as terminal and stop sending state-changing actions for it.
AlreadyInitialized	Contract Already Initialized	The contract was initialized more than once.	Run initialization only once per deployment.
AlreadyAppealed	Appeal Already Exists	An appeal already exists for this invoice.	Check whether an appeal is already open before creating another one.
AppealWindowClosed	Appeal Window Closed	The appeal deadline has passed.	Submit the appeal before the deadline, or update the contract configuration.
NotDefaulted	Invoice Not Defaulted	The invoice is not in the defaulted state required by this action.	Wait until the invoice is defaulted, then retry the default-specific action.
AlreadyInQueue	Already In Funding Queue	This LP has already joined the funding queue for this invoice.	Skip re-joining if the LP is already queued, or remove the existing entry first.
NotApprovedFunder	Not Approved Funder	This LP is not the funder approved by the priority queue.	Wait for queue resolution and fund only when the contract assigns that LP as the funder.
InvoiceAppealed	Invoice Under Appeal	The invoice is currently in the appealed state.	Wait for the appeal to resolve before retrying settlement or closure flows.
AlreadyDisputed	Invoice Already Disputed	This invoice is already disputed.	Check dispute status before filing and avoid re-opening an active dispute.
NotDisputed	Invoice Not Disputed	The invoice is not in a disputed state.	Open a dispute first, or call the correct function for the current state.
InvoiceDisputed	Invoice Under Dispute	The invoice is under dispute and cannot proceed through normal settlement.	Resolve or dismiss the dispute before retrying normal invoice actions.
DueDateTooSoon	Due Date Too Soon	The due date is earlier than the minimum allowed horizon.	Choose a later due date that satisfies the contract minimum lead time.
DueDateTooFar	Due Date Too Far	The due date is later than the maximum allowed horizon.	Reduce the due date to fall within the contract configured maximum range.
SelfInvoice	Self-Invoice Not Allowed	The payer and invoice creator are the same address.	Use distinct payer and submitter addresses before resubmitting.
OverpaymentRejected	Overpayment Rejected	The payment amount exceeds the remaining amount due.	Pay exactly the remaining amount or query the outstanding balance first.
PayerReputationTooLow	Payer Reputation Too Low	The payer reputation is below the configured minimum threshold.	Improve the payer reputation score, or adjust the minimum threshold through governance.
PayerUnverified	Payer Not Verified	The oracle did not verify the payer when verification was required.	Use a verified payer account, or disable payer verification if not required.
OracleDataStale	Oracle Data Stale	The oracle response is older than the configured freshness window.	Refresh the oracle data and retry the transaction.
OracleCircuitOpen	Oracle Circuit Open	The oracle verification circuit breaker is open after repeated stale data, so funding was rejected.	Wait for the oracle feed to recover and the circuit to reset before retrying funding.
MaxInvoiceAmountExceeded	Max Invoice Amount Exceeded	The invoice amount exceeds the maximum allowed by the current contract configuration.	Split the invoice into smaller amounts or request a governance cap increase.
GlobalVolumeCapExceeded	Global Volume Cap Exceeded	This transaction would exceed the contract global volume cap.	Wait for the volume window to reset or request a cap increase through governance.
QueueNotMature	Funding Queue Not Mature	The funding queue has not matured enough to resolve.	Wait for the queue window to elapse before resolving the invoice.
InsufficientLiquidity	Insufficient Liquidity	There is not enough liquidity available in the pool to complete this transaction.	Please try a smaller amount or wait for more liquidity to be added.
InsufficientBalance	Insufficient Balance	Your wallet does not have enough balance to cover the transaction.	Ensure you have enough funds, including necessary network fees.
ArithmeticOverflow	Calculation Error	A mathematical error occurred during the transaction.	Please review the transaction amounts and try again.
TokenNotSupported	Unsupported Token	The selected token asset is not supported by this contract.	Try using a different asset for this transaction.
ContractPaused	Contract Paused	The smart contract is currently paused for maintenance or security reasons.	Please try again later when the network resumes operations.
InvalidInvoiceState	Invalid Invoice State	The invoice is not in the correct state to perform this action.	Verify the current status of the invoice before proceeding.
FeeOnTransferToken	Unsupported Token Type	This token implements fee-on-transfer and cannot be added to the ILN allowlist.	Choose a standard token that transfers the full amount without deducting a fee.
InvalidMultisigConfig	Invalid Multisig Configuration	The multisig configuration for this action is invalid or incomplete.	Verify the multisig signer setup and required thresholds before retrying.

Unknown/error fallback

When the UI cannot match an incoming error to a known contract code, it falls back to the generic message below:

• Title: Transaction Failed
• Message: The transaction could not be completed due to an unexpected error.
• Remediation: Please try again or contact support if the issue persists.