Error Handling

The Aerosync platform surfaces errors from two sources: the widget (client-side, via the onError callback) and the API (server-side, via HTTP status codes and a structured error body). This page covers widget errors.

Widget Errors

When an error occurs inside the Aerosync widget, the onError callback fires with a plain string payload. The same string is delivered to every SDK — Web, React Native, iOS, Android, and Flutter.

Payload format

Type: ERROR_TYPE | Code: CODE | Message: MESSAGE

Examples:

Type: INCORRECT_CREDENTIALS | Code: AC-117 | Message: Sorry, we encountered an issue while linking your account. Please ensure your account and routing numbers are correct.

Type: POLLING_TIMEOUT | Code: AR-100 | Message: No response received from the user within the expected time frame. Please try again later.

Type is the machine-readable classification, Code is the AR- or AC- identifier from the table below, and Message is the copy already shown to the user inside the widget.

Make sure onError is always defined in your widget configuration so these events are captured and logged:

onError: (event) => {
  console.error('Aerosync widget error:', event)
  // log or forward to your monitoring — no UI changes needed
}

Important behavioural notes

onError is a logging hook, not an instruction to act.

• Do not close the widget when onError fires. The widget owns the recovery path. Closing it cancels a session the user could still complete.
• Do not display the error on your own UI. The widget already renders the error screen, the copy in Message, and the appropriate retry, manual-entry, or exit action. Showing your own error on top of it duplicates or contradicts what the user is looking at.
• onError is not a terminal event. Most errors are recoverable — the user can retry in the widget and still reach onSuccess. Never treat a single onError as a failed session.
• Multiple events per session are normal. Retries, repeated MFA attempts, and multi-account linking each emit their own event.
• onError is not a substitute for onClose. If the user abandons the flow from an error screen, you receive onClose, not another onError.

Use these events for logging, monitoring, and funnel analytics. When contacting [email protected], include the Code and the timestamp.

Error codes

AR codes are raised by the widget itself. AC codes originate from the Aerosync backend and are mapped by the widget to a user-facing error screen.