Response Codes
Waffo API response format:
{
"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 |
Handling E0001 Unknown Status
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 |
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
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);
}
}
