Skip to navigation
Security & Operations

SDK Integration Troubleshooting

Diagnose Trading Widget, Agent SDK, signing, webhook, timeout, and environment problems before escalating a support request.
View as Markdown

Start with the environment, timestamp, and business identifier for the failed operation. A structured check usually separates configuration problems from authentication, network, and asynchronous-processing issues.

  1. Confirm the affected environment and base URL.
  2. Record the UTC time range and the first failing request.
  3. Identify the module: Trading Widget, Agent SDK, REST API, WebSocket, or webhook.
  4. Capture the request ID, partner user ID, agentOrderNo, order ID, or webhook event ID.
  5. Check recent code, credential, IP whitelist, or deployment changes.
  6. Reproduce with the smallest safe test case.

Trading Widget issues

SymptomLikely causeFix
iframe requests partner local domainbaseUrl is missingPass baseUrl: ‘https://app.6mm.com’.
iframe is invisible or very shortParent container has no heightSet container height or pass height.
token_provider_missingpartner-token mode has no providerAdd auth.tokenProvider.
auth_exchange_failedInvalid, expired, or mismatched embed tokenCheck backend token response and channelId.

Agent SDK issues

SymptomLikely causeFix
Signature rejectedWrong secret, clock drift, or manually changed signed fieldsLet SDK generate signing fields and sync server time.
Duplicate funds movement riskNew order number used after timeoutQuery by original agentOrderNo first.
PROCESSING treated as failurePending state misunderstoodWait for webhook or call queryOrder.
Webhook processed multiple timesRetry behavior without idempotencyAdd idempotency key and final-state checks.

Evidence to capture

IntegrationUseful evidence
Trading WidgetPage URL, SDK version path, browser console, failed network requests, onError payload, and container dimensions.
Agent SDKSDK language/version, base URL, UTC timestamp, request ID, agentOrderNo, response code, and sanitized logs.
WebhookDelivery time, event or business key, signature-validation result, processing state, and sanitized raw-body hash.
REST APIMethod, path, environment, request ID, response code, and sanitized parameters.

Never include passwords, access tokens, API secrets, full signatures, private keys, or unredacted personal data in diagnostics.

Before escalating

  • Retry only when the operation is documented as safe to retry.
  • After a timeout, query the original business identifier instead of creating a new one.
  • Confirm the system clock and credential environment for signature errors.
  • Preserve the first failure and any later retry results.
  • Use the Support Request Template to send a complete, redacted report.
Trading Widget Quick Start

Verify script loading, container size, configuration, and callbacks.

Secrets & Signing

Check Agent SDK credentials, clocks, and signed fields.

Webhooks & Idempotency

Review callback verification and duplicate-event handling.

Java v0.3.0 diagnostics

SymptomCheck and recovery
Funding request has an unknown resultKeep the original agentOrderNo; call queryWalletTransfer with the original environment. Do not use queryOrder.
Simulation UI shows unexpected fundsCheck frontend tradingMode separately from backend environment; account isSimulatedUser does not route requests.
Query error 6905Back off using the shared partner quota, then retry the same cursor and filters through the SDK.
Query error 6904Reduce concurrent queries and narrow the time window; contact support if persistent.
Invalid or expired cursorRestart the same fixed history window and deduplicate saved records.
Missing new Java methodCheck the resolved Maven artifact against public tag v0.3.0; remove conflicting dependencies according to your artifact policy.

Query and error reference · Upgrade guide

Webhook receiving issues

SymptomCheck and handling
No retry after returning failure JSONCheck whether the endpoint still returns HTTP 200. Delivery uses only the HTTP status, not a success indicator in the body.
Retries continue after 401 or 409Non-2xx responses follow the existing retry policy; investigate signatures, notification content, or merchant configuration.
Empty idempotency key for a liquidation warningThe current WebhookVerifier.idempotencyKey only extracts funds-event identities. After signature and ownership checks, validate notificationId and build the warning key in merchant code. Never use an empty key.
Duplicate notification after successful processingPersist deduplication within merchant and environment scope. Return 2xx for identical duplicates; record conflicts and return non-2xx for the same ID with a different body.
Warning not processedAccept liquidation.warning and historical LIQUIDATION_WARNING; do not group distinct notification IDs by user, episode, or event type and discard them.
Accepted notification loses its pending taskSave a task reliably before returning 2xx; starting an in-memory async task is insufficient.

Event fields and compatibility · HTTP responses and reliable acknowledgement