nick/nick-doc
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: AML scope note, human-blocked items, Task #11 pre-flight inventory

Browse Source 
- Add AML scope note to Handoff - RN Multichain Probe (sanctions-only vs full KYT)
- Add human-blocked section with 3 precise next steps for owner
- Create Task 11 Pre-flight Inventory: library choice, dev/prod flow, admin UI gaps, backend gaps, risks, acceptance criteria
This commit is contained in:
Siavash Sameni
2026-05-28 20:42:42 +04:00
parent ddc0434819
commit 81625d35d2
18 changed files with 398 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
03 - API Reference/Error Codes.md
View File

@@ -35,7 +35,7 @@ Uncaught errors are formatted by [`shared/middleware/errorHandler.ts`](../../bac
}
```
Legacy routes (chiefly `/api/users` legacy paths, `/api/marketplace` legacy paths, `/api/payment/decentralized/*`, parts of `/api/payment/shkeeper/*`) return ad-hoc shapes such as `{ "error": "..." }` or `{ "success": false, "message": "..." }`. Treat any non-`2xx` response as an error and read whichever of `error` / `message` is present.
Legacy routes (chiefly `/api/users` legacy paths, `/api/marketplace` legacy paths, and `/api/payment/decentralized/*`) return ad-hoc shapes such as `{ "error": "..." }` or `{ "success": false, "message": "..." }`. Treat any non-`2xx` response as an error and read whichever of `error` / `message` is present.
## HTTP status mapping
@@ -43,7 +43,7 @@ Legacy routes (chiefly `/api/users` legacy paths, `/api/marketplace` legacy path
| --- | --- | --- |
| `200 OK` | Successful read or mutation | Most `GET`s, idempotent `PUT`s/`PATCH`s |
| `201 Created` | Resource created | `POST /api/marketplace/purchase-requests`, `POST /api/auth/register` (when user created), `POST /api/marketplace/reviews` |
| `202 Accepted` | Async accepted (provider webhooks) | SHKeeper webhook acknowledgement |
| `202 Accepted` | Async accepted (provider webhooks) | Request Network webhook accepted while safety checks are pending |
| `204 No Content` | Mutations with no body to return | Rare — most endpoints return the updated object |
| `400 Bad Request` | Validation failure, malformed input | `express-validator` errors, bad MongoIds, missing fields |
| `401 Unauthorized` | Missing or invalid JWT | `Access token required`, `Invalid or expired token` |
@@ -53,7 +53,7 @@ Legacy routes (chiefly `/api/users` legacy paths, `/api/marketplace` legacy path
| `423 Locked` | Account temporarily locked | After repeated failed logins (Redis-tracked) |
| `429 Too Many Requests` | Rate limit hit | Currently issued only by per-feature Redis limits (auth / AI); global limiter is disabled |
| `500 Internal Server Error` | Unhandled exception | Caught by `errorHandler`; included stack trace in dev |
| `502 Bad Gateway` | Upstream provider failure | OpenAI / SHKeeper unreachable |
| `502 Bad Gateway` | Upstream provider failure | OpenAI / Request Network unreachable |
## Application error codes
@@ -89,11 +89,10 @@ Handled in `errorHandler`:
| Provider | Endpoint | Status on success | Status on signature mismatch |
| --- | --- | --- | --- |
| SHKeeper pay-in | `POST /api/payment/shkeeper/webhook` | 200 `{ success: true }` | 401 `{ success: false }` (then ignored) |
| SHKeeper payout | `POST /api/payment/shkeeper/payout/webhook` | 200 / 400 with `{ success, message, data }` | 400 |
| Request Network pay-in | `POST /api/payment/request-network/webhook` | 200 `{ success: true }` or 202 while safety checks are pending | 401 `{ success: false }` |
| Generic payment callback | `POST /api/payment/callback` | 200 `{ success: true, message }` | 400 |
If a webhook is acknowledged with non-2xx, the provider re-delivers (SHKeeper retries every 60 seconds).
If a webhook is acknowledged with non-2xx, the provider may re-deliver. Persisting delivery evidence and replay support is a launch-hardening item in [[Request Network Integration Constraints]].
## Client guidance