Error Handling

Both SDKs throw a TransFiError when an API call fails.

PropertyNode.jsPythonTypeDescription
Messageerror.messagestr(e)stringHuman-readable error message
Status codeerror.statusCodee.status_codenumberHTTP status code, e.g. 400, 401, 500
Response bodyerror.responseDatae.response_dataanyRaw JSON response from the API
const { TransFiPaymentAPI, TransFiError } = require("transfi-checkout");

try {
  const paymentUrl = await client.createPaymentInvoice({ ... });
} catch (error) {
  if (error instanceof TransFiError) {
    console.error("TransFi API Error:", error.message);
    console.error("HTTP Status:", error.statusCode);   // e.g. 401, 400
    console.error("API Response:", error.responseData); // full error body
  } else {
    // Network error, timeout, etc.
    console.error("Unexpected error:", error.message);
  }
}
from transfi import TransFiPaymentAPI, TransFiError

try:
    payment_url = api.create_payment_invoice(request)
except TransFiError as e:
    print("API Error:   ", e)
    print("Status Code: ", e.status_code)
    print("Response:    ", e.response_data)
except Exception as e:
    # Network error, timeout, etc.
    print("Unexpected error:", e)
try {
    String paymentUrl = api.createPaymentInvoice(request);
    System.out.println("Payment URL: " + paymentUrl);
    // Redirect user to paymentUrl to complete payment
} catch (transfiError e) {
    System.err.println("Error: " + e.getMessage());
    System.err.println("Status Code: " + e.getStatusCode());
    System.err.println("Response: " + e.getResponseData());
}
try {
    $paymentUrl = $api->createPaymentInvoice($paymentData);
    echo 'Checkout URL: ' . $paymentUrl . PHP_EOL;
} catch (TransFiError $e) {
    echo 'API Error   : ' . $e->getMessage() . PHP_EOL;
    echo 'Status Code : ' . $e->getStatusCode() . PHP_EOL;
    echo 'Response    : ' . json_encode($e->getResponseData(), JSON_PRETTY_PRINT) . PHP_EOL;
}

Common HTTP status codes

StatusMeaningCommon cause
400Bad RequestMissing required fields or invalid parameter values
401UnauthorizedInvalid or missing API keys
404Not FoundpaymentLinkId does not exist in your account
500Server ErrorTemporary TransFi API issue — retry with backoff