Nudge troubleshooting

Work through the symptom that matches what you're seeing. If none match, the Troubleshooting FAQ covers cross-app questions and a general debugging approach.

REST connection test fails

Symptom	Fix
401	Align the Bearer token: regenerate in Settings → ERP connection and update middleware config
DNS error / timeout	Verify the HTTPS URL is publicly reachable; check firewall allowlists for Alderstone egress
Invalid JSON	Return `schemaVersion: "1"` on all success and error bodies

Sync returns no invoices

Confirm modifiedSince isn't filtering out every row; the first full sync omits it, but if your middleware applies a stale default cursor you'll see empty imports.
Verify your middleware maps invoice statuses to the ACCREC-style values Alderstone expects (AUTHORISED, SUBMITTED, PAID).
Check the ERP credentials inside your middleware; an upstream auth failure often surfaces as an empty list instead of an error.

Push not reaching the ERP

Outbound push has prerequisites (see Sync & push flows:

An active native or REST connection must exist.
Invoice push requires the invoice's debtor to be linked to the ERP (erpDebtorId from a prior sync).
Payment push requires the target invoice to already have an erpInvoiceId from a prior push or sync.

OAuth errors (native integration)

Error param	Meaning
`invalid_state`	Session expired; retry Connect in Settings
`no_refresh_token`	Enable the `offline_access` scope on your OAuth client registration
`save_failed`	Configuration save failed; retry Connect, or contact support if it persists

Requests failing after key rotation

Rotating revokes the old key immediately; update the middleware configuration right away, or every request returns 401 until you do. See API key management.

Reproduce the failure outside the app using the debtors list example with your base URL and Bearer token. If cURL succeeds but sync fails, re-check the configured base URL in Settings → ERP connection for typos or trailing slashes.