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 both.
When an error occurs inside the Aerosync widget, the onError callback fires with a plain string response in the following format:
ERROR_TYPE | Code: CODE | Message: MESSAGE
INCORRECT_CREDENTIALS | Code: AC-117 | Message: Sorry, we encountered an issue while linking your account. Please ensure your account and routing numbers are correct.
POLLING_TIMEOUT | Code: AR-100 | Message: No response received from the user within the expected time frame. Please try again later.
Make sure `onError` is always defined in your widget configuration so these events are captured and logged:
```javascript
onError: (event) => {
console.error('Aerosync widget error:', event);
// parse the string or display a fallback message to the user
}
AR codes are widget-specific errors unrelated to a particular API endpoint.
| Code | Type | Message |
|---|
AR-100 | POLLING_TIMEOUT | No response received from the user within the expected time frame. Please try again later. |
AR-500 | SERVER_ERROR | A server error occurred. Please try again later. |
All Aerosync API errors return a structured JSON body alongside the HTTP status code. The error code always starts with AC followed by a three-digit number.
The tables below list every AC code by endpoint, along with the HTTP status and a description of what caused it.
| HTTP Status | Code | Message | Description |
|---|
| 400 Bad Request | AC-100 | Required attributes are missing or not in a valid format. | The request body is malformed or incomplete. Verify all required fields are present and correctly formatted. |
| 401 Forbidden | AC-101 | Invalid API key and secret. | The supplied credentials are not authorized. Double-check your apiKey and apiSecret. |
| HTTP Status | Code | Message | Description |
|---|
| 400 Bad Request | AC-100 | Required attributes are missing or not in a valid format. | The request body is malformed or incomplete. Verify all required fields are present and correctly formatted. |
| 403 Forbidden | AC-001 | Invalid API key and secret. | The supplied credentials are not authorized. Check your Authorization header and token validity. |
| 404 Not Found | AC-102 | User <connectionId> not found. | The connectionId in the path parameter is invalid. Confirm the user completed the widget onSuccess flow before making this call. |
| 400 Bad Request | AC-103 | The FI failed to send account number, routing number, or balance. | The financial institution returned incomplete data. Surface a user-friendly error and prompt the user to reconnect. |
| 400 Bad Request | AC-104 | We are having issues connecting to your bank. Reconnect your bank or reach out to [email protected] to resolve the issue. | There are connection issues with the FI. Retry with exponential backoff. If the issue persists, prompt the user to reconnect via the widget. |
| HTTP Status | Code | Message | Description |
|---|
| 400 Bad Request | AC-100 | Missing required request parameters: [connectionId]. | The request body is malformed or incomplete. Verify all required fields are present and correctly formatted. |
| 403 Forbidden | AC-001 | Invalid API key and secret. | The supplied credentials are not authorized. Check your Authorization header and token validity. |
| 400 Bad Request | AC-104 | We are having issues connecting to your bank. Reconnect your bank or reach out to [email protected] to resolve the issue. | There are connection issues with the FI. Retry with exponential backoff. If the issue persists, prompt the user to reconnect. |
| 405 Method Not Allowed | AC-105 | Balance check not available for manually linked users. | Balance checks are not supported for manually linked accounts. Check the connectionMethod field on GET /accounts before calling this endpoint. |
| 400 Bad Request | AC-106 | For security purposes, the FI has paused sharing account information for this user. To continue, the user can reconnect to the FI. | The FI has revoked the connection. The user must re-authenticate via the widget to restore access. |
| HTTP Status | Code | Message | Description |
|---|
| 400 Bad Request | AC-100 | Missing required request parameters: [connectionId]. | The request body is malformed or incomplete. Verify all required fields are present and correctly formatted. |
| 403 Forbidden | AC-001 | Invalid API key and secret. | The supplied credentials are not authorized. Check your Authorization header and token validity. |
| 400 Bad Request | AC-102 | User <connectionId> not found. | The connectionId in the path parameter is invalid. Confirm the user completed the widget onSuccess flow before making this call. |
| 400 Bad Request | AC-104 | We are having issues connecting to your bank. Reconnect your bank or reach out to [email protected] to resolve the issue. | There are connection issues with the FI. Retry with exponential backoff. If the issue persists, prompt the user to reconnect. |
| 405 Method Not Allowed | AC-107 | Balance refresh not available for manually linked users. | Balance refresh is not supported for manually linked accounts. Check connectionMethod on GET /accounts before calling this endpoint. |
| 429 Too Many Requests | AC-108 | Account has been temporarily blocked due to too many incorrect MFA attempts. | The user has been MFA-locked. Do not retry automatically. Surface a message to the user and contact [email protected] if needed. |
| HTTP Status | Code | Message | Description |
|---|
| 400 Bad Request | AC-100 | Missing required request parameters: [connectionId]. | The request body is malformed or incomplete. Verify all required fields are present and correctly formatted. |
| 403 Forbidden | AC-001 | Invalid API key and secret. | The supplied credentials are not authorized. Check your Authorization header and token validity. |
| 404 Not Found | AC-102 | User <connectionId> not found. | The connectionId in the path parameter is invalid. |
| 400 Bad Request | AC-104 | We are having issues connecting to your bank. Reconnect your bank or reach out to [email protected] to resolve the issue. | There are connection issues with the FI. |
| 404 Not Found | AC-109 | Job <job_id> not found. | The job_id in the path parameter is invalid. Use the jobId returned from the create job response — do not construct it manually. |
| HTTP Status | Code | Message | Description |
|---|
| 400 Bad Request | AC-100 | Missing required request parameters: [connectionId]. | The request body is malformed or incomplete. Verify all required fields are present and correctly formatted. |
| 403 Forbidden | AC-001 | Invalid API key and secret. | The supplied credentials are not authorized. Check your Authorization header and token validity. |
| 404 Not Found | AC-102 | User <connectionId> not found. | The connectionId in the path parameter is invalid. |
| 400 Bad Request | AC-104 | We are having issues connecting to your bank. Reconnect your bank or reach out to [email protected] to resolve the issue. | There are connection issues with the FI. |
| 405 Method Not Allowed | AC-110 | Your MFA session has expired. Please reauthenticate to continue. | The user took too long to respond to the MFA challenge. Re-initiate the job and re-launch the MFA widget from scratch. |
| HTTP Status | Code | Message | Description |
|---|
| 400 Bad Request | AC-100 | Missing required request parameters: [connectionId]. | The request body is malformed or incomplete. Verify all required fields are present and correctly formatted. |
| 403 Forbidden | AC-001 | Invalid API key and secret. | The supplied credentials are not authorized. Check your Authorization header and token validity. |
| 404 Not Found | AC-102 | User <connectionId> not found. | The connectionId in the path parameter is invalid. |
| 400 Bad Request | AC-104 | We are having issues connecting to your bank. Reconnect your bank or reach out to [email protected] to resolve the issue. | There are connection issues with the FI. |
| 405 Method Not Allowed | AC-111 | Identity jobs are not available for manually linked users. | Identity jobs require a widget-linked account. If the user linked manually, prompt them to re-link via the widget. |
| 409 Conflict | AC-112 | Conflict — another job currently in progress. | A job is already running for this connectionId. Check job state server-side before triggering a new request. |
| HTTP Status | Code | Message | Description |
|---|
| 400 Bad Request | AC-100 | Missing required request parameters: [connectionId]. | The request body is malformed or incomplete. Verify all required fields are present and correctly formatted. |
| 403 Forbidden | AC-001 | Invalid API key and secret. | The supplied credentials are not authorized. Check your Authorization header and token validity. |
| 404 Not Found | AC-102 | User <connectionId> not found. | The connectionId in the path parameter is invalid. |
| 400 Bad Request | AC-104 | We are having issues connecting to your bank. Reconnect your bank or reach out to [email protected] to resolve the issue. | There are connection issues with the FI. |
| 400 Bad Request | AC-113 | For security purposes, the FI has paused sharing account information for this user. To continue, the user can reconnect to the FI. | Authentication has failed for the expected user. The user must re-authenticate via the widget. |
| HTTP Status | Code | Message | Description |
|---|
| 400 Bad Request | AC-100 | Missing required request parameters: [connectionId]. | The request body is malformed or incomplete. Verify all required fields are present and correctly formatted. |
| 403 Forbidden | AC-001 | Invalid API key and secret. | The supplied credentials are not authorized. Check your Authorization header and token validity. |
| 404 Not Found | AC-102 | User <connectionId> not found. | The connectionId in the path parameter is invalid. |
| 400 Bad Request | AC-104 | We are having issues connecting to your bank. Reconnect your bank or reach out to [email protected] to resolve the issue. | There are connection issues with the FI. |
| 409 Conflict | AC-112 | Conflict — another job currently in progress. | A job is already running for this connectionId. Check job state server-side before triggering a new request. |
| 405 Method Not Allowed | AC-114 | Transaction jobs are not available for manually linked users. | Transaction jobs require a widget-linked account. If the user linked manually, prompt them to re-link via the widget. |
| HTTP Status | Code | Message | Description |
|---|
| 400 Bad Request | AC-100 | Missing required request parameters: [connectionId]. | The request body is malformed or incomplete. Verify all required fields are present and correctly formatted. |
| 403 Forbidden | AC-001 | Invalid API key and secret. | The supplied credentials are not authorized. Check your Authorization header and token validity. |
| 404 Not Found | AC-102 | User <connectionId> not found. | The connectionId in the path parameter is invalid. |
| 400 Bad Request | AC-104 | We are having issues connecting to your bank. Reconnect your bank or reach out to [email protected] to resolve the issue. | There are connection issues with the FI. |
| 405 Method Not Allowed | AC-115 | Transaction data not available for manually linked users. | Transaction data requires a widget-linked account. If the user linked manually, prompt them to re-link via the widget. |
| HTTP Status | Code | Message | Description |
|---|
| 400 Bad Request | AC-100 | Missing required request parameters: [connectionId]. | The request body is malformed or incomplete. Verify all required fields are present and correctly formatted. |
| 403 Forbidden | AC-001 | Invalid API key and secret. | The supplied credentials are not authorized. Check your Authorization header and token validity. |
| 404 Not Found | AC-102 | User <connectionId> not found. | The connectionId in the path parameter is invalid. |
| 400 Bad Request | AC-104 | We are having issues connecting to your bank. Reconnect your bank or reach out to [email protected] to resolve the issue. | There are connection issues with the FI. |
| 404 Not Found | AC-109 | Balance refresh job for <connectionId> not found. | The job_id in the path parameter is invalid. Use the jobId returned from the create job response — do not construct it manually. |
