OrderBridge troubleshooting

Work through the symptom that matches what you're seeing. Most integration failures fall into one of these categories; if none match, the Troubleshooting FAQ covers cross-app questions and a general debugging approach.

Connection test fails on save

Saving a REST integration runs POST /health and a sample POST /sale-draft. See the connection test.

Symptom	Cause	Fix
401 on `/health`	Token mismatch	Align the Bearer token: regenerate in Alderstone and update middleware config
Timeout	Firewall or slow ERP	Allow Alderstone egress through your firewall; keep `/health` fast (don't call the ERP from it)
422 validation	Missing `schemaVersion`	Echo `"schemaVersion": "1"` on all response bodies
`/sale-draft` fails	Sample SKU unknown in ERP	Accept the demo SKU in your test environment, or return a validation error with a clear `error` message

Match returns no products

Confirm the search query is at least 2 characters. The OrderBridge UI won't search below that.
Verify the ERP catalogue is populated and your middleware search is forgiving about case and partial matches.
Check middleware logs for upstream ERP errors being swallowed and returned as an empty hits array. Surface them as errors instead.

Price check always mismatches

Return systemUnitPrice in the ERP currency, with the same precision as the PO line.
If tier selection depends on the PO's value, use the optional poUnitPrice field from the request.

Submit fails after successful match

Ensure ship/bill addresses were matched to real ERP address IDs. Returned from /catalog/customers/addresses for REST, or matched natively.
Verify the sale-draft lines use ERP-valid SKUs and positive integer quantities.

Customer sync returns "No customers"

REST: an empty-string query must return the first page of customers, not an empty array. See the search customers reference.
Native: verify the API credentials have customer read scope.

Requests failing after key rotation

Rotating in Settings → Integrations → API keys revokes the old key immediately. Update the middleware configuration right away. Any request still validated against the old token returns 401. See API key management.

Replay a request with cURL

Reproducing a failure outside the app isolates whether the problem is in Alderstone configuration or your middleware:

curl -X POST "$BASE_URL/health" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"schemaVersion":"1"}'

Use the base URL and token from Settings, then compare the response to the REST API reference. If cURL succeeds but the app fails, re-check the configured base URL for typos or trailing slashes.