---
updatedAt: 2026-05-25T02:09:16.000Z
agentTools:
  projectIndex: https://checkout-docs.transfi.com/llms.txt
---

# Error Handling

Both SDKs throw a `TransFiError` when an API call fails.

| Property      | Node.js              | Python            | Type   | Description                                |
| :------------ | :------------------- | :---------------- | :----- | :----------------------------------------- |
| Message       | `error.message`      | `str(e)`          | string | Human-readable error message               |
| Status code   | `error.statusCode`   | `e.status_code`   | number | HTTP status code, e.g. `400`, `401`, `500` |
| Response body | `error.responseData` | `e.response_data` | any    | Raw JSON response from the API             |

```javascript Node.js
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);
  }
}
```
```python
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)
```
```java
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());
}

```
```php
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

| Status | Meaning      | Common cause                                        |
| :----- | :----------- | :-------------------------------------------------- |
| `400`  | Bad Request  | Missing required fields or invalid parameter values |
| `401`  | Unauthorized | Invalid or missing API keys                         |
| `404`  | Not Found    | `paymentLinkId` does not exist in your account      |
| `500`  | Server Error | Temporary TransFi API issue — retry with backoff    |