Skip to content
Developerhome
Product homepage
Banking Service

Handling Errors

  Less than to read

Flow diagram showing sync status and retry logic

Overview

When integrating with Sage’s Banking Service via the Provider API, robust error handling ensures reliable sync and transparency for downstream systems. This guide outlines how to manage failures, trigger appropriate sync statuses, and implement a retry strategy using exponential or fixed backoff.

Handling Sync Failures

If your integration encounters an error while syncing data (e.g., account, transaction, or balance data), you must set the sync status to FAILED in your sync.status payload.

Set Sync Status to FAILED

Use the POST /sync endpoint to report a failed sync.

{
  "status": "FAILED",
  "reason": "Authentication error: token expired",
  "timestamp": "2025-05-06T08:30:00Z"
}
  • status: Must be set to FAILED.
  • reason: Provide a human-readable explanation (ideally for UI/debugging purposes).
  • timestamp: The time the failure was detected.

Retry Strategy

We recommend a retry mechanism to ensure transient errors (like timeouts or temporary authorization issues) do not lead to data loss.

Use a 30-minute retry interval after a failure before attempting the next sync attempt.

  • Retry up to 3 times over a 90-minute window.
  • If the error persists, notify the user or support team, and suspend syncing for that bank connection.

Example Retry Flow

Attempt Result Action Delay Until Next Try
1 FAILED Retry scheduled 30 minutes
2 FAILED Retry scheduled 30 minutes
3 FAILED Final retry attempt 30 minutes
4 FAILED Notify and suspend —

Optional: Exponential Backoff

Alternatively, use exponential backoff for more advanced control:

  • 1st retry: after 15 minutes
  • 2nd retry: after 30 minutes
  • 3rd retry: after 60 minutes

Logging and Monitoring

Maintain internal logs of all sync failures and retry attempts. We recommend capturing:

  • Timestamp
  • Error type and message
  • Affected `principalID` and `externalRef`
  • Retry count

These logs help with debugging and improve support response times.

Additional Notes

  • No Retry on Permanent Failures: Do not retry on 4XX errors such as invalid credentials or user-deleted accounts.
  • Use `IN_PROGRESS` Between Retries: Optionally set sync status to `IN_PROGRESS` during retry attempts to reflect pending resolution.
  • Postman Collection: Try simulating sync failures using the Sync endpoint in Postman.

What’s Next?

Once your retry logic is working as expected in sandbox, verify it with production onboarding scenarios. For more, visit Stage 4: Go Live and Support.

Was this helpful?