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.
| Code | HTTP | Retried | What to do |
|---|---|---|---|
VALIDATION_FAILED | 400 | A field is absent or malformed; the message says which. Fix the call. | |
BAD_CURSOR | 400 | The list cursor is not one the service gave. Start from the first page. | |
IDEMPOTENCY_KEY_MISSING | 400 | A state change came without an Idempotency-Key. The client sends one itself; add it to a hand-made call. | |
IDEMPOTENCY_KEY_REUSED | 409 | The key was used with another body. Use a new key for a new call. | |
IDEMPOTENCY_IN_PROGRESS | 409 | yes | The first call with this key is still running. Wait and send the same call again. |
SIGNATURE_REQUIRED | 401 | The route needs a signed request or a read grant. Give createClient a signer. | |
SIGNATURE_EXPIRED | 401 | The request's time is more than 300 s off the service's clock. Set the machine's clock. | |
NONCE_REUSED | 401 | The nonce was used before. Sign the request again. | |
ROLE_NOT_ALLOWED | 403 | The key holds no role on this line that the route takes. Check the line's registry entry. | |
LINE_NOT_FOUND | 404 | The service serves no such line. A mainnet line answers this too. | |
NOT_FOUND | 404 | No such payout, step or take-over on this line, or the receiver and amount are not the payout's. | |
UNKNOWN_ASSET | 422 | The asset is not in the line's basket. Use a basket symbol or its token contract. | |
REFUSED | 409 | The service refused the action. The reasons say why. | |
FROZEN | 409 | Untangled's admin froze the line. Wait for the freeze to lift. | |
LIMIT_EXCEEDED | 409 | Over a limit: a cap, the cover, or the partial repayment rule. The reasons give the amounts that would pass. | |
SCREENING_FAILED | 409 | The receiver did not pass screening. The reasons say why. | |
STALE_PRICE | 422 | A basket price is older than its limit. Try again after the next price update. | |
STATE_CONFLICT | 409 | The 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_CONTRACTS | 422 | The chain's rules refused the batch in simulation. The reasons carry the contract's error. | |
SIGNATURE_INVALID | 400 | The step signature does not verify for the step signer. Sign the step with the key it names. | |
STEP_EXPIRED | 410 | The step's approvals lapsed. Make the step again and sign it within the minute. | |
SUBMIT_FAILED | 502 | The chain did not take the transaction. Read the step to see its state before trying again. | |
CHAIN_UNAVAILABLE | 503 | yes | The service could not reach the chain. The client retries; try again later. |
RATE_LIMITED | 429 | yes | Too many calls from this address. The client waits Retry-After and retries. |
MAINNET_REFUSED | 403 | The service does not run mainnet lines yet. | |
INTERNAL | 500 | The service failed. Send the request id to Untangled. | |
SIGNER_MISMATCH | SDK | The step names another key, or the signer signed with another key. Sign with the key the step names. | |
PREIMAGE_MISMATCH | SDK | The preimage is not the batch the step claims, or outlives its expiry. Do not sign it; report the step. | |
TERMS_MISMATCH | SDK | The step does not match your terms. Do not sign it; check your figures against the step. | |
APPROVAL_EXPIRED | SDK | The approval ended before the current ledger. Make the step again. | |
MAINNET_NOT_READY | SDK | Mainnet has no code pins yet. No option turns this off. | |
NETWORK_ERROR | SDK | yes | The call did not reach the service. The client retries a call that is safe to repeat. |
TIMEOUT | SDK | yes | No answer within 60 s. The client retries a call that is safe to repeat. |
BAD_RESPONSE | SDK | The response was not the JSON the SDK expects. Check baseUrl. |