# How to handle errors in API workflows on Bubble.io: Step-by-Step Guide

- Tool: Bubble
- Difficulty: Intermediate
- Time required: 20-25 min
- Compatibility: Starter plan+ (backend workflows require paid plan)
- Last updated: March 2026

## TL;DR

Bubble's backend API workflows have limited built-in error handling, but you can build a robust error management system using the API Connector's error response setting, error logging to a dedicated Data Type, retry logic with recursive scheduling, and admin notification workflows.

## Overview: Error Handling in API Workflows

Backend API workflows are the backbone of server-side processing in Bubble, but they have limited built-in error handling. When something goes wrong — an external API call fails, data validation catches an issue, or a workflow times out — you need a system to catch the error, log it, optionally retry, and alert the right people. This tutorial shows you how to build that system.

## Before you start

- A Bubble app on a Starter plan or above with backend workflows enabled
- At least one existing backend API workflow
- Basic familiarity with the API Connector plugin
- Understanding of Schedule API Workflow action

## Step-by-step guide

### 1. Enable error responses in the API Connector

If your backend workflow calls external APIs via the API Connector, open the Plugins tab and click on your API Connector configuration. For each API call, check the box labeled Include errors in response and allow workflow actions to continue. This is critical — without this setting, API errors stop the entire workflow immediately with no way to handle them. With it enabled, the workflow continues and you can check the response for errors.

> Pro tip: This setting is per-API-call, not global. Enable it on every call where you want graceful error handling.

**Expected result:** API calls that return errors no longer crash the workflow — instead, the error data is accessible in subsequent actions.

### 2. Create an ErrorLog Data Type for tracking failures

Go to the Data tab and create a new Data Type called ErrorLog. Add these fields: workflow_name (text), error_message (text), error_code (text), parameters (text — store a JSON summary of input parameters), retry_count (number, default: 0), resolved (yes/no, default: no), and Created Date (auto). This gives you a searchable log of every error that occurs in your backend workflows.

**Expected result:** An ErrorLog Data Type is ready to store structured error records from any backend workflow.

### 3. Add error detection and logging to your workflow

In your backend workflow, after an action that might fail (like an API call), add a conditional action: Only when Result of Step X's status_code is not 200 (or however your API reports errors). In that conditional branch, add Create a new ErrorLog with the workflow name, error message from the response, error code, and a text summary of the parameters. This logs the failure for later debugging. After logging, you can either stop the workflow or continue with fallback logic.

**Expected result:** Every error is captured in the ErrorLog Data Type with full context for debugging.

### 4. Build retry logic with recursive scheduling

Add a parameter called retry_count (number) to your backend workflow. After detecting an error, check if retry_count is less than your maximum (e.g., 3). If so, add a Schedule API Workflow action that re-schedules the same workflow with the same parameters, incrementing retry_count by 1, and setting the scheduled date to Current date/time + seconds: 30 (a 30-second delay). If retry_count equals the max, log a final failure and stop retrying.

> Pro tip: Use exponential backoff by multiplying the delay: 30 seconds for retry 1, 60 for retry 2, 120 for retry 3.

**Expected result:** Failed workflows automatically retry up to your configured maximum with increasing delays between attempts.

### 5. Notify admins of critical failures

After the final retry fails (or for critical errors that should not retry), add an action to send an email notification. Use the Send email action with the admin's email address, including the workflow name, error message, parameters, and retry count in the body. Alternatively, create a Notification Data Type and show unresolved errors on an admin dashboard using a Repeating Group filtered to resolved = no.

**Expected result:** Admins receive an email or see a dashboard notification when backend workflows fail after all retries.

## Complete code example

File: `Workflow summary`

```text
ERROR HANDLING WORKFLOW SUMMARY
================================

DATA STRUCTURE:
  ErrorLog Data Type:
    - workflow_name (text)
    - error_message (text)
    - error_code (text)
    - parameters (text)
    - retry_count (number, default: 0)
    - resolved (yes/no, default: no)

BACKEND WORKFLOW: process-order
  Parameters:
    - order_id (text)
    - customer_email (text)
    - retry_count (number, default: 0)

  Action 1: API Connector → Call external payment API
    (Include errors in response: enabled)

  Action 2 (Only when Result status ≠ 200):
    Create a new ErrorLog:
      → workflow_name: "process-order"
      → error_message: Result's body's error
      → error_code: Result's status_code
      → parameters: "order: [order_id], email: [customer_email]"
      → retry_count: retry_count

  Action 3 (Only when status ≠ 200 AND retry_count < 3):
    Schedule API Workflow: process-order
      → order_id: order_id
      → customer_email: customer_email
      → retry_count: retry_count + 1
      → Scheduled date: Current date/time +(seconds): 30 * (retry_count + 1)

  Action 4 (Only when status ≠ 200 AND retry_count = 3):
    Send email:
      → To: admin@yourapp.com
      → Subject: "ALERT: process-order failed after 3 retries"
      → Body: Error details + parameters

  Action 5 (Only when Result status = 200):
    → Continue with normal success actions

API CONNECTOR SETTING:
  Each API call → Check "Include errors in response
  and allow workflow actions to continue"
```

## Common mistakes

- **Not enabling error responses in the API Connector** — Without this setting, any API error immediately crashes the workflow with no opportunity to handle it gracefully Fix: Check Include errors in response and allow workflow actions to continue on every API Connector call
- **Building retry logic without a maximum retry count** — Without a termination condition, the workflow retries infinitely, burning WUs and potentially crashing your app Fix: Always include a retry_count parameter and stop retrying when it exceeds your maximum (typically 3-5)
- **Not logging enough context with errors** — An error message alone is not enough to debug — you need to know which parameters were passed and what state the workflow was in Fix: Log the workflow name, all parameter values, error code, error message, and retry count in your ErrorLog

## Best practices

- Enable error responses on every API Connector call that your backend workflows use
- Create a dedicated ErrorLog Data Type — never rely solely on server logs which have limited retention
- Implement retry logic with exponential backoff for transient failures
- Set a maximum retry count (3-5) to prevent infinite retry loops
- Send admin notifications for errors that exhaust all retries
- Build an admin dashboard that shows unresolved errors filtered from the ErrorLog
- Review your ErrorLog regularly to identify patterns and fix root causes

## Frequently asked questions

### Does Bubble have built-in try/catch for backend workflows?

No. Bubble does not have native try/catch in backend workflows. The closest equivalent is enabling error responses in the API Connector and using conditional actions to check for errors after each step.

### How long are server logs retained?

Server logs are retained for 6 hours on the Free plan and longer on paid plans (up to 30 days on Team/Enterprise). This is why logging to a dedicated Data Type is essential for debugging.

### Can I handle errors from database operations, not just API calls?

Database operations in Bubble rarely throw catchable errors. If a Create or Make Changes action fails due to Privacy Rules, use the An unhandled error occurs event at the page level to catch it.

### Will retry logic consume extra Workload Units?

Yes. Each retry runs the full workflow again, consuming WUs. This is why you should limit retries (3-5 max) and use exponential backoff to avoid burning through your allocation.

### How do I debug a backend workflow that fails silently?

Create a Debug Data Type and add Create a new Debug actions between each step in your workflow, logging the current state and values. This gives you a step-by-step trace of the workflow execution.

### Can RapidDev help with complex error handling architectures?

Yes. RapidDev has built enterprise error handling systems in Bubble including centralized error dashboards, automated retry queues, and integration with external monitoring services like PagerDuty and Slack alerts.

---

Source: https://www.rapidevelopers.com/bubble-tutorial/handle-errors-api-workflows-bubble
© RapidDev — https://www.rapidevelopers.com/bubble-tutorial/handle-errors-api-workflows-bubble