Reference & Troubleshooting

Integration Recommendations

View as Markdown

Use these recommendations as a production-readiness baseline. They complement the endpoint reference and help integrations recover safely from timeouts, reconnects, duplicate requests, and credential incidents.

Authentication and secrets

  • Prefer API Key signing for server-side trading programs and JWT for user-driven frontend actions.
  • Keep apiSecret in backend secret management. It is shown only once and must never be sent to a browser or mobile client.
  • Apply the minimum required API Key permissions and restrict source IPs when the integration environment supports stable egress addresses.
  • Disable or delete a leaked key immediately, then review request logs before issuing a replacement.

Request validation and idempotency

  • Before placing orders, query /v1/public/market/symbols and validate tickSize, stepSize, minimum notional value, and maximum quantity locally.
  • Generate a unique clientOrderId for every order write so requests can be reconciled after a disconnect.
  • Preserve the original identifier when an HTTP result is uncertain. Query the existing order before creating a replacement request.
  • Treat decimal amounts and prices as strings or decimal types, not binary floating-point values.

Order and WebSocket state

  • Determine final state after cancel, cancel-all, or amend operations from private WebSocket events or a REST query.
  • Treat every reconnect as a new WebSocket session and restore all required subscriptions.
  • Check order-book continuity with endVersion. If a version gap appears, discard the local book and resubscribe for a fresh snapshot.
  • Deduplicate private order and account events before applying them to balances, positions, or partner records.

Logging, monitoring, and retries

  • Record request ID, client order ID, HTTP status, API business code, latency, and retry count without logging secrets or full tokens.
  • Retry only operations documented as safe, using bounded exponential backoff and jitter.
  • Alert on authentication failures, signature errors, rate-limit responses, WebSocket reconnect loops, sequence gaps, and order reconciliation differences.
  • Keep server clocks synchronized because authentication and signing depend on timestamps.

Before production

  • Exercise timeout, duplicate request, reconnect, key rotation, and webhook retry scenarios in a non-production environment.
  • Assign owners for credential rotation, trading incidents, webhook failures, and reconciliation.
  • Complete the production launch checklist and use the support request template when escalation is required.