401 Unauthorized
Cause: missing/expired session cookie.
Fix: log in again and include cookie:
curl -X POST $API_BASE/api/auth/login -H 'Content-Type: application/json' \
-d '{"email":"[email protected]","password":"••••••"}' -c cookies.txt
Then retry with -b cookies.txt.
403 Forbidden
Cause: insufficient role or KYC required.
Fix: ask an Admin for role adjustment, or complete Settings → Compliance.
404 Not Found
Cause: wrong ID or resource outside your org.
Fix: check the ID, ensure the right organization is active, verify permissions.
Validation error
Cause: schema mismatch.
Fix: adjust payload to required types/fields.
Example error
{"code":"VALIDATION_ERROR","issues":[{"path":["currency"],"message":"Must be a 3-letter code"}]}
Webhook signature invalid
Cause: body parsed before verify, or wrong secret.
Fix: use express.raw() and correct secret.
app.post('/api/webhooks/stripe', express.raw({type:'application/json'}), handler);
Payment stuck as pending
Cause: webhook not delivered/processed.
Fix: replay from provider dashboard; check logs; ensure handler is idempotent.
File upload failed
Cause: exceeds size/type limits or MIME mismatch.
Fix: compress large files, convert to allowed formats, ensure correct MIME type.
SSE not receiving events
Cause: blocked by CORS/cookies, or server closed stream.
Fix: allow your origin in CORS; ensure withCredentials: true; check server logs.
KYC required error
Cause: action gated by KYC.
Fix: complete verification in Settings → Compliance; then retry.
CORS error in browser
Cause: origin not in allow‑list.
Fix: add your app domain to CORS config; don’t use * with credentials.