Skip to main content

Errors

Catch a PayfiError​

Every failure is a PayfiError from core, with the code, the service's reasons, the HTTP status and the requestId. error.retryable is true for the codes marked "yes" below; the client has already retried those twice with back-off. After NETWORK_ERROR or TIMEOUT, a POST without an Idempotency-Key comes back to you at once: the step requests anyone may make, the screening, the liquidation quote and the read grant. Call them again yourself; they record nothing.

errors.ts
// Every failure is a PayfiError: the code, the service's reasons, the HTTP
// status and the request id.
// bun run errors.ts
import { createClient } from '@crediolabs/payfi-sdk/api'
import { PayfiError } from '@crediolabs/payfi-sdk/core'

const url = process.env.PAYFI_URL ?? 'https://payfi-beta.untangled.finance'
const client = createClient({ baseUrl: url })

try {
await client.line('no-such-line').get()
} catch (e) {
if (!(e instanceof PayfiError)) throw e
console.log(`${e.code} (HTTP ${e.status}), request ${e.requestId}`)
console.log(e.message)
for (const reason of e.reasons) console.log(` ${reason}`)
console.log(e.retryable
? 'The same call may succeed later. The client already retried it twice.'
: 'Change the call before trying again.')
}

On 25 October 2026 against the beta it printed:

LINE_NOT_FOUND (HTTP 404), request req_f5bf4576025607ea337bb9c2
this service serves no line no-such-line
Change the call before trying again.

Codes​

The service's codes come with an HTTP status. The SDK raises the codes marked "SDK" itself, before or without a call.

CodeHTTPRetriedWhat to do
VALIDATION_FAILED400A field is absent or malformed; the message says which. Fix the call.
BAD_CURSOR400The list cursor is not one the service gave. Start from the first page.
IDEMPOTENCY_KEY_MISSING400A state change came without an Idempotency-Key. The client sends one itself; add it to a hand-made call.
IDEMPOTENCY_KEY_REUSED409The key was used with another body. Use a new key for a new call.
IDEMPOTENCY_IN_PROGRESS409yesThe first call with this key is still running. Wait and send the same call again.
SIGNATURE_REQUIRED401The route needs a signed request or a read grant. Give createClient a signer.
SIGNATURE_EXPIRED401The request's time is more than 300 s off the service's clock. Set the machine's clock.
NONCE_REUSED401The nonce was used before. Sign the request again.
ROLE_NOT_ALLOWED403The key holds no role on this line that the route takes. Check the line's registry entry.
LINE_NOT_FOUND404The service serves no such line. A mainnet line answers this too.
NOT_FOUND404No such payout, step or take-over on this line, or the receiver and amount are not the payout's.
UNKNOWN_ASSET422The asset is not in the line's basket. Use a basket symbol or its token contract.
REFUSED409The service refused the action. The reasons say why.
FROZEN409Untangled's admin froze the line. Wait for the freeze to lift.
LIMIT_EXCEEDED409Over a limit: a cap, the cover, or the partial repayment rule. The reasons give the amounts that would pass.
SCREENING_FAILED409The receiver did not pass screening. The reasons say why.
STALE_PRICE422A basket price is older than its limit. Try again after the next price update.
STATE_CONFLICT409The payout or line is in another state: settled already, a lapsed release (renew it), no debt to repay. With detail.settling or detail.changed, ask again after Retry-After.
REFUSED_BY_CONTRACTS422The chain's rules refused the batch in simulation. The reasons carry the contract's error.
SIGNATURE_INVALID400The step signature does not verify for the step signer. Sign the step with the key it names.
STEP_EXPIRED410The step's approvals lapsed. Make the step again and sign it within the minute.
SUBMIT_FAILED502The chain did not take the transaction. Read the step to see its state before trying again.
CHAIN_UNAVAILABLE503yesThe service could not reach the chain. The client retries; try again later.
RATE_LIMITED429yesToo many calls from this address. The client waits Retry-After and retries.
MAINNET_REFUSED403The service does not run mainnet lines yet.
INTERNAL500The service failed. Send the request id to Untangled.
SIGNER_MISMATCHSDKThe step names another key, or the signer signed with another key. Sign with the key the step names.
PREIMAGE_MISMATCHSDKThe preimage is not the batch the step claims, or outlives its expiry. Do not sign it; report the step.
TERMS_MISMATCHSDKThe step does not match your terms. Do not sign it; check your figures against the step.
APPROVAL_EXPIREDSDKThe approval ended before the current ledger. Make the step again.
MAINNET_NOT_READYSDKMainnet has no code pins yet. No option turns this off.
NETWORK_ERRORSDKyesThe call did not reach the service. The client retries a call that is safe to repeat.
TIMEOUTSDKyesNo answer within 60 s. The client retries a call that is safe to repeat.
BAD_RESPONSESDKThe response was not the JSON the SDK expects. Check baseUrl.