Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.privataswap.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Format

{
  "error": {
    "code": "INVALID_PAIR",
    "message": "Pair BTC->FAKE not supported",
    "request_id": "req_abc123..."
  }
}
Always include request_id when contacting support — it lets us pull the full trace in <10 s.

​
Codes

CodeHTTPMeaningWhat to do
INVALID_KEY401API key missing, malformed, or revoked.Check X-API-Key header and key state in dashboard.
RATE_LIMITED429Bucket exhausted.Respect Retry-After. SDK does this automatically.
INVALID_PAIR400Pair not supported across any provider.Show generic “Pair unavailable” UX.
AMOUNT_TOO_LOW400Below provider minimum.Show min from /limits.
AMOUNT_TOO_HIGH400Above provider maximum.Show max from /limits.
NO_PROVIDERS_AVAILABLE503All 50+ providers down or filtered out by your geo policy.Retry in 30 s.
PROVIDER_ERROR502Selected provider returned a transient error.Re-quote, we’ll route to a fallback.
QUOTE_EXPIRED410quote_id no longer valid (5 min TTL).Get a fresh /estimate and retry.
ORDER_NOT_FOUND404Wrong order_id or order older than our retention.Check spelling; orders retained 18 months.
DUPLICATE_ACTIVE_ORDER409Logical-dup detection: same partner_order_ref already has an open order.Reuse the existing order_id from response body.
REFUND_WINDOW_EXPIRED409/refund-action called past refund_window_hours.Order auto-resolved via refund_preference.default.
REFUND_NOT_PROGRAMMATIC409Provider is ticket-based.Show ticket UX, don’t call /refund-action.
STABLE_TARGET_REQUIRED400convert_to_stable requested without stable_target.Set stable_target.
WEBHOOK_PAUSED409Webhook resume attempted on already-active webhook.Idempotent — safe to ignore.
SCOPE_REQUIRED403Key missing required scope (e.g. webhook:admin).Request scope expansion in dashboard.

​
Error body extensions

For form-validation-style errors we add a fields array: 
{
  "error": {
    "code": "INVALID_PAIR",
    "message": "Validation failed",
    "fields": [
      { "field": "to", "issue": "currency XYZ not in /currencies" }
    ]
  }
}

​
SDK exception mapping

The JS SDK maps every code to a typed subclass of PrivataError: 
import { PrivataError, RateLimitedError, QuoteExpiredError } from "@privata/wallet-api";

try {
  await privata.createOrder({ ... });
} catch (e) {
  if (e instanceof RateLimitedError) {
    await sleep(e.retryAfterMs);
  } else if (e instanceof QuoteExpiredError) {
    // re-quote
  }
}