> ## 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](/docs/en/developer-docs/tools-and-references/developer-tools/error-codes.md).

## 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.

### 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` |
| Python | `WaffoUnknownStatusError` | `WaffoError` |
| PHP | `WaffoUnknownStatusError` | `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.).

### 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);
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.