Skip to main content

Troubleshooting, QA Plan & Playbooks

Most-used endpoints, fast fixes, what to test pre-launch, and incident runbooks.

C
Written by Catalin Fetean
Updated over 3 weeks ago

Audience: Developers, Support, Ops, Compliance
Outcomes: Working clients; reliable sync; disciplined pre-launch checks; clear escalations

API quick reference

Orders

POST /api/orders GET /api/orders/:orderId GET /api/orders

Deliverables

POST /api/orders/:orderId/deliverables POST /api/orders/:orderId/deliverables/:deliverableId/accept POST /api/orders/:orderId/deliverables/:deliverableId/reject

Escrow

POST /api/escrow/release

Errors

  • 401 login, 403 role/KYC, 404 wrong ID, 400 validation

  • Idempotency: provide a stable reference; server dedupes where possible

Troubleshooting (quick map)

Symptom → Fast fix

  • Order stuck in DepositPending → Provider webhook not delivered; replay; verify signature; check logs

  • Upload blocked (type/size) → Convert/compress; check MIME; split archive

  • Duplicate payout → Ensure unique reference; idempotent release handler

  • Wrong timezone on due dates → Store UTC; display user locale

  • Counterparty cannot see deliverable → Share order; verify org context & partner link

Support debug checklist

  • Confirm user org and role

  • Capture x-correlation-id, request/response sample, timestamp

  • Check webhook delivery logs + processed event IDs

  • Reproduce with minimal curl using the same cookie

QA test plan (pre-launch)

Happy paths

  • Create order with 2 milestones

  • Upload deliverables; accept/reject → resubmit → accept

  • Fund deposit via card; webhook ⇒ DepositPaid; set InProgress

  • Partial then final release; invoice updated

  • SSE events arrive in browser

Negative paths

  • Oversized file rejected

  • Duplicate release blocked by idempotency

  • Missing KYC blocks release (403)

  • Webhook with bad signature rejected (400)

Reports

  • Export orders CSV; totals & counts correct

  • Evidence bundle contains deliverables + decisions + releases

Operational playbooks

Incident: provider webhook outage

  • Switch to manual reconciliation: query provider by reference; mark payments in admin back-office with notes

  • After recovery, replay events; verify no double releases (idempotent handlers)

Incident: large backlog of uploads

  • Increase worker concurrency; stagger retries; communicate delay via UI banner

Incident: dispute spike

  • Add pre-acceptance checklist to milestones; enforce reviewer SLAs; analyze common rejection reasons

Escalations

  • P1: money movement incorrect → on-call engineer + finance lead

  • P2: delayed reviews/minor webhooks → PM + support

Did this answer your question?