Error reference

Rampwire uses conventional HTTP status codes with JSON bodies.

Response shape

Most errors return:

{ "error": "Human readable or machine token" }

Validation failures may include:

{
  "error": { "fieldErrors": {}, "formErrors": [] },
  "message": "Validation failed"
}

Successful agent pay idempotent replay includes extra keys (idempotent_replay, etc.) — not errors.

---

HTTP status codes

Code	Meaning	What to do
400	Bad input / JSON / business rule	Fix body; read error
401	Missing or invalid session, LP key, or WebSocket auth	Refresh credentials
403	Forbidden — wrong order owner, admin-only route, invalid agent key	Check token type and permissions
404	Unknown order_id, currency without LP, etc.	Verify ids and routing
409	Conflict / wrong state — e.g. claim lost race, settle before confirm	Re-fetch status, apply retry logic
413	Payload too large (LP receipt upload)	Shrink file (< ~12 MB)
429	Rate limit / connection limit	Backoff; reduce concurrency

---

LP-specific errors

Symptom	Typical status	Fix
Unauthorized on /api/lp/{lp_key}/…	401	Bearer token must equal path {lp_key} and exist in DB
Order not claimable	409	Already claimed — wait for next order
Insufficient collateral	400	Deposit collateral before claiming large notionals
Too many concurrent connections for this LP key	429 (WS preflight)	Close unused sockets
Order not found or not assigned to this LP (receipt)	403	Wrong order_id

---

Agent API errors

Symptom	Typical status	Fix
Agent API key required (Bearer rk_live_…)	403	Include bearer rk_live_*
Invalid or revoked agent API key	403	Rotate key via admin
Unknown user_id — create the user via auth before paying	400	Create user first
No LP available for KES	404	Ensure approved LP publishes that currency
Could not calculate rate for {sym}	400	Pick usdt/usdc or ensure pricing integrations are live
Too many requests	429	Slow down POST /api/v1/pay

---

Webhook receiver errors

Issue	Mitigation
Signature mismatch	Hash raw body with WEBHOOK_SECRET; compare lowercase hex
Missing signature header	Reject (401) — likely not from Rampwire

---

WebSocket (pre-upgrade) errors

Returned as HTTP JSON before the socket opens:

{ "error": "Unauthorized" }

{ "error": "Too many concurrent connections for this LP key" }

---

Troubleshooting flow

1. Log status, response JSON, and correlation ids (order_id, payment_id, Idempotency-Key).
2. GET /api/v1/status/{orderId} or GET /api/orders/{orderId} to learn ground truth.
3. For LP automation, confirm GET /api/lp/{lp_key}/dashboard shows expected collateral.
4. Exponential backoff on 429 and transient network failures.

---

Documentation map

• LP API reference
• Agent API reference
• Webhooks