> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> A guide to Waffo API error code categories and handling Unknown Status exceptions.

## Response Codes

Waffo API response format:

```json theme={null}
{
  "code": "0",
  "msg": "Success",
  "data": { ... }
}
```

* `code` of `"0"` indicates success
* On failure, `code` is an error code string (e.g., `"A0003"`, `"E0001"`)
* The response field is named `msg` (not `message`)

## Error Code Categories

| Prefix | Category               | Description                                        |
| ------ | ---------------------- | -------------------------------------------------- |
| 0      | Success                | —                                                  |
| A      | Merchant error         | Invalid parameters, insufficient permissions, etc. |
| B      | User error             | Insufficient balance, payment timeout, etc.        |
| C      | System error           | Channel rejection, system errors, etc.             |
| D      | Risk Control rejection | Transaction blocked by Risk Control                |
| E      | Unknown error          | **Critical: payment may have succeeded**           |

For the full error code list, see [Error Code Reference](/en/developer-docs/tools-and-references/developer-tools/error-codes).

## Handling E0001 Unknown Status

<Warning>
  **This is the most critical exception scenario.** When you encounter a network timeout, connection interruption, or the server returns `E0001`, the payment status is unknown.
</Warning>

### Principles

* **Do not assume failure**: a network timeout does not mean the payment failed
* **Do not automatically close the order**: the payment may have already completed on the channel side
* **Do not create a new order**: use the original `paymentRequestId` to query

### Error Types in the SDK

| Language | Unknown status error            | Client error       |
| -------- | ------------------------------- | ------------------ |
| Node.js  | `WaffoUnknownStatusError`       | `WaffoError`       |
| Java     | `WaffoUnknownStatusException`   | `WaffoException`   |
| Go       | `*core.WaffoUnknownStatusError` | `*core.WaffoError` |

<Note>
  The SDK has only two error types. `WaffoUnknownStatusError`/`Exception` means the payment may have succeeded, while `WaffoError`/`Exception` indicates a client-side error (configuration, signature, etc.).
</Note>

### SDK Error Codes

| Error code | Type          | Description                                 |
| ---------- | ------------- | ------------------------------------------- |
| S0001      | UnknownStatus | Network error (timeout, connection failure) |
| E0001      | UnknownStatus | Server returned unknown status              |
| S0002      | Error         | Invalid public key                          |
| S0003      | Error         | Signature failed                            |
| S0004      | Error         | Response signature verification failed      |
| S0005      | Error         | Request serialization failed                |
| S0007      | Error         | Invalid private key                         |

### Handling Flow

```
Network timeout / E0001 / WaffoUnknownStatusError
    │
    ▼
Query using the original paymentRequestId
    │
    ├── PAY_SUCCESS found    → Update local status to success
    ├── ORDER_CLOSE found    → Update local status to failure
    └── Still unknown        → Wait for Webhook notification
```

### Code Example

```typescript theme={null}
import { WaffoUnknownStatusError, WaffoError } from '@waffo/waffo-node';

try {
  const response = await waffo.order().create(params);
  if (response.isSuccess()) {
    // code === "0", handle success
  } else {
    // API returned an error code (e.g. A0003), safe to treat as failure
  }
} catch (error) {
  if (error instanceof WaffoUnknownStatusError) {
    // Important: payment may have succeeded! Query before deciding
    const inquiry = await waffo.order().inquiry({ paymentRequestId });
    if (inquiry.isSuccess()) {
      const status = inquiry.getData().orderStatus;
      await updateOrderStatus(paymentRequestId, status);
    }
    // If the query also fails, wait for a Webhook
  } else if (error instanceof WaffoError) {
    // Client error (configuration, signature), safe to retry after fixing
    console.error('Client error:', error.errorCode, error.message);
  }
}
```