docs(ios): explanation on double events in faq

Author: hyochan

docs/docs/guides/faq.md

@@ -254,6 +254,37 @@ const handlePurchaseError = (error) => {
 };
 ```
 
+### I sometimes see both a success and an error for one subscription purchase
+
+This can briefly happen due to StoreKit 2 event ordering and native background work. If you've already received a success and processed it, you can safely ignore a transient error that arrives shortly afterwards.
+
+Tip (dedupe in app logic):
+
+```tsx
+const lastSuccessAtRef = useRef(0);
+
+const { finishTransaction } = useIAP({
+  onPurchaseSuccess: async (purchase) => {
+    lastSuccessAtRef.current = Date.now();
+    await finishTransaction({ purchase, isConsumable: false });
+  },
+  onPurchaseError: (error) => {
+    if (error.code === 'E_USER_CANCELLED') return;
+    if (error.code === 'E_SERVICE_ERROR') {
+      const dt = Date.now() - lastSuccessAtRef.current;
+      if (dt >= 0 && dt < 1500) return; // Ignore spurious error
+    }
+    Alert.alert('Purchase Failed', error.message);
+  },
+});
+```
+
+Because of this timing model, all request* APIs (e.g., `requestPurchase`) are event-driven, not promise-based:
+
+- `requestPurchase()` does not resolve with a result. It triggers the native flow and you must handle outcomes via `onPurchaseSuccess`/`onPurchaseError` (when using `useIAP`) or `purchaseUpdatedListener`/`purchaseErrorListener`.
+- Avoid relying on `await requestPurchase(...)` for the final outcome; multiple events and inter-session completions are possible.
+- This design ensures your app remains robust when the store delivers updates after app restarts or in edge timing cases.
+
 ### How do I handle network errors during purchases?
 
 Network errors during purchases are tricky because the purchase might still go through. Always: