11.1 Understanding Errors
Errors are inevitable in automation—APIs fail, data is invalid, services go down. The difference between a fragile system and a robust one is how well you understand and handle errors. This section teaches you to recognize, understand, and resolve errors in Taibles.
What Are Errors?
The Concept
An error occurs when a column's execution fails to complete successfully.
Simple analogy: Like a recipe step that can't be completed
Recipe step: "Add milk"
Error: No milk in fridge
Result: Can't proceedIn Taibles:
Column: "Enrich Contact"
Error: API authentication failed
Result: Cell shows error stateWhy Errors Happen
External reasons (outside your control):
- API services are down or slow
- Network connectivity issues
- Third-party service rate limits
- Account credentials expired
- External service changed its API
Configuration reasons (you can fix):
- Wrong API credentials
- Account not connected
- Incorrect dependency setup
- Missing required data
- Wrong condition logic
Data reasons (input quality):
- Invalid email format
- Null values where required
- Data type mismatches
- Out-of-range values
The "Unsuccessful" State
Visual Indicators
When a cell fails, you see:
Failed Cell Display
When a cell fails, you see this badge:
1. Blue badge in cell
- Label: "Unsuccessful"
- Icon: Lightning bolt (⚡)
- Color: Blue (info variant)
2. Column header shows fail count
- Example: "3 FAILED" in red
- Clicking navigates to first failed cell
3. Button appears to view error details
- Red button with alert icon (⚠️)
- Click to open error sidebar
Failed Cell with Error Details Button
When you hover over a failed cell, a button appears that lets you view the error details:
What Gets Stored
When execution fails, Taibles captures:
1. Error title (Short description)
- Example: "Authentication Failed"
- Example: "Rate Limit Exceeded"
- Example: "Validation Error"
2. Error description (Detailed message)
- Example: "Your API key is invalid or expired. Please reconnect your Clearbit account."
- Example: "Email address is not valid. Expected format: user@domain.com"
3. Timestamp
- When the error occurred
- Helps track if error is recent or stale
4. Stack trace (Technical details)
- Full error trace for debugging
- Shows exact code location of failure
- Available for technical users
5. HTTP details (For API errors)
- Status code (e.g., 401, 429, 500)
- HTTP method (GET, POST, etc.)
- URL that was called
- Response body from service
- Request headers
6. Input data (What was being processed)
- Row data that caused error
- Helps reproduce the issue
- Context for debugging
Viewing Error Details
The Error Sidebar
When you click the red error button, a sidebar slides in from the right showing all the error information:
Error Details Sidebar
When you click the error button, a sidebar slides in from the right showing detailed error information:
The sidebar shows:
What went wrong (highlighted section)
- User-friendly explanation
- Plain English description
- What you need to do to fix it
Technical Details
- Status code (with color-coded badge)
- HTTP method used
- URL that was called
Response Body
- What the API returned
- Error messages from the service
Input Data
- What data was being processed
- Helps you understand the context
Stack Trace (for developers)
- Technical debugging information
- Only visible to admins
Error Types
| Error Type | Common Causes | What to Do |
|---|---|---|
Configuration | Account not connected, wrong settings | Fix configuration in Settings |
Validation | Invalid data format, missing required fields | Correct data in failed rows |
API Errors | Service down, authentication failed, rate limits | Reconnect account or wait for service |
Timeout | Operation took too long, slow API | Retry or optimize operation |
Rate Limit | Too many requests too fast | System handles automatically |
Permission | Insufficient access rights | Update account permissions |
Logic | Condition or logic error | Fix condition or add null checks |
Type 1: Configuration Errors
What they are: Settings are wrong or incomplete
Common causes:
- Account not connected
- API key missing or incorrect
- Dependency not configured
- Wrong node method selected
Example 1: Missing Account
Error title: "Account Not Found"
Error description: "No HubSpot account configured for this column. Please connect an account in Settings."
What happened: Column tries to call HubSpot API, but no account is connected
How to recognize:
- Error mentions "account", "credentials", "configuration"
- Occurs immediately when column runs
- Happens for all rows (not just specific ones)
How to fix:
- Go to Settings → Accounts
- Click "Add Account"
- Select service (e.g., HubSpot)
- Complete authorization
- Return to column settings
- Select newly connected account
- Save
- Re-run failed cells
Example 2: Reference to Missing Data
Error title: "Validation Error"
Error description: "Required field is missing or empty."
What happened: The column expected data from another column, but it wasn't there
How to recognize:
- Error mentions "missing", "not found", "required"
- Points to specific column name
- May affect only some rows (where data is missing)
How to fix:
- Check that the referenced column exists
- Verify the referenced column has data
- Add the column to dependencies if missing
- Ensure referenced column runs before this one
- Add a condition to only run when data exists
Type 2: Validation Errors
What they are: Data doesn't meet expected format or requirements
Common causes:
- Invalid email format
- Phone number wrong format
- Required field is empty
- Number out of range
- Date in wrong format
Example: Invalid Email
Error title: "Validation Failed"
Error description: "Email address 'not-an-email' is not valid. Expected format: user@domain.com"
What happened: Node expected valid email, got malformed string
How to recognize:
- Error mentions "validation", "invalid", "format"
- Points to specific data field
- Occurs for specific rows (with bad data)
How to fix:
- Review data in failed rows
- Correct invalid entries manually
- Add validation column before this one
- Add condition to skip rows with invalid data
- Re-run after data correction
Type 3: API Errors
What they are: External service request failed
Common causes:
- Service is down (HTTP 500, 503)
- Authentication failed (HTTP 401, 403)
- Rate limit exceeded (HTTP 429)
- Resource not found (HTTP 404)
- Bad request (HTTP 400)
Example 1: Authentication Failed
Error title: "Authentication Failed"
Error description: "HTTP 401 Unauthorized: Invalid API key"
HTTP details:
- Status: 401
- Method: GET
- URL: https://api.clearbit.com/v2/enrichment/...
- Response:
{"error": "Invalid API key"}
What happened: API key is wrong, expired, or service revoked access
How to recognize:
- HTTP status 401 or 403
- Error mentions "auth", "unauthorized", "forbidden", "API key"
- Affects all rows (not just specific ones)
How to fix:
- Go to Settings → Accounts
- Find the service account (e.g., Clearbit)
- Click "Reconnect"
- Re-authorize or update API key
- Test connection
- Re-run failed cells
Example 2: Rate Limit Exceeded
Error title: "Rate Limit Exceeded"
Error description: "HTTP 429 Too Many Requests: You have exceeded your rate limit of 100 requests per hour."
HTTP details:
- Status: 429
- Headers:
Retry-After: 3600(1 hour)
What happened: Too many API calls in short period
How to recognize:
- HTTP status 429
- Error mentions "rate limit", "too many requests", "quota"
- Occurs after processing many rows
How to fix:
- Enable rate limiting in column configuration:
- Max requests: 90 per hour (below limit)
- Window: 3600 seconds (1 hour)
- Cells automatically queue and retry
- OR: Wait for limit reset (check
Retry-Afterheader) - OR: Upgrade API plan for higher limits
See Chapter 8: Rate Limiting for detailed guide
Example 3: Service Down
Error title: "Service Unavailable"
Error description: "HTTP 503 Service Unavailable: API is temporarily down for maintenance."
What happened: External service is temporarily unavailable
How to recognize:
- HTTP status 500, 502, 503, 504
- Error mentions "unavailable", "down", "maintenance"
- Sudden spike in failures across all rows
How to fix:
- Check service status page (e.g., status.hubspot.com)
- Wait for service to recover
- Set up automatic retries (see Section 11.2)
- After service recovers:
- Filter failed cells
- Right-click → "Recalculate cells"
- Select "Failed cells only (retry)"
Type 4: Timeout Errors
What they are: Operation took too long to complete
Common causes:
- Slow API response
- Large data processing
- Network latency
- Heavy computation
Example: API Timeout
Error title: "Timeout"
Error description: "Operation timed out after 30 seconds. The API did not respond in time."
What happened: API call took longer than timeout limit
How to recognize:
- Error mentions "timeout", "took too long", "exceeded time limit"
- Occurs randomly (when service is slow)
- May affect rows with large data
How to fix:
Option A: Increase timeout (if configurable)
- Check node configuration
- Look for timeout setting
- Increase to 60-90 seconds
Option B: Optimize operation
- Reduce data size sent to API
- Use batch endpoints if available
- Split large operations into smaller ones
Option C: Retry failed cells
- Temporary slowness often resolves
- Retry usually succeeds
Type 5: Rate Limit Errors
What they are: Execution frequency limits exceeded
Common causes:
- Too many cells executing simultaneously
- Processing high volume of rows too fast
- External service rate limits
- Internal rate limits configured
Example: Rate Limit Active
Error title: "Rate Limit Exceeded"
Error description: "Column rate limit of 100 requests per hour exceeded. Cell will retry automatically when limit window resets."
What happened: Column hit configured rate limit
How to recognize:
- Error mentions "rate limit"
- Cell may show "Rate Limited" state (yellow badge) instead of "Unsuccessful" (blue)
- Multiple cells affected simultaneously
- Cells auto-retry when window resets
What to do:
- Nothing required: System handles automatically
- Cells queue and retry when limit allows
- Monitor yellow cells (they'll turn green when processed)
See Chapter 8: Rate Limiting for full details
Type 6: Permission Errors
What they are: Access denied to resource or operation
Common causes:
- Account authorization scope insufficient
- API key lacks permissions
- Account role too limited
- Resource belongs to different user/org
Example: Insufficient Permissions
Error title: "Permission Denied"
Error description: "HTTP 403 Forbidden: Your API key does not have permission to create contacts. Required scope: crm.objects.contacts.write"
What happened: API key or account token lacks required permissions
How to recognize:
- HTTP status 403
- Error mentions "permission", "forbidden", "scope", "access denied"
- Specific to certain operations (read works, write doesn't)
How to fix:
- Review required permissions for operation
- Go to Settings → Accounts
- Reconnect account with correct scopes
- During authorization, ensure all permissions granted
- If API key: Generate new key with required permissions
- Save and re-run
Type 7: Logic Errors
What they are: Condition or logic produces unexpected result
Common causes:
- Condition error
- Wrong comparison operator
- Type mismatch in comparison
- Null/undefined handling missing
Example: Condition Evaluation Failed
Error title: "Condition Evaluation Error"
Error description: "Cannot evaluate condition. Referenced column is null."
What happened: Condition references null value, causing error
How to recognize:
- Error in condition field (not execution)
- Mentions "condition", "evaluation"
- Points to specific issue
How to fix:
- Add null check to condition
- Or use default value in condition
- Or ensure dependency always produces value
Error Patterns to Recognize
Understanding error patterns helps you diagnose issues faster:
| Pattern | What You See | Likely Cause | Solution |
|---|---|---|---|
All Rows Failing | Every cell shows "Unsuccessful" | Configuration error | Fix settings once |
Random Failures | Some succeed, others fail | Temporary service issues | Retry failed cells |
Specific Rows | Same rows always fail | Bad data in those rows | Fix data or add validation |
First Batch Fails | Initial rows fail, rest work | Rate limit hit | Enable rate limiting |
Sudden Failures | Worked before, all fail now | Account expired/changed | Reconnect account |
Pattern 1: All Rows Failing
Symptom: Every row in column shows "Unsuccessful"
Likely cause: Configuration error
- Account not connected
- API credentials wrong
- Node misconfigured
Action: Fix configuration once, affects all rows
Pattern 2: Random Rows Failing
Symptom: Some rows succeed, others fail randomly
Likely cause: Temporary issues
- API intermittent failures
- Network instability
- Service slowness causing timeouts
Action: Retry failed cells (often succeeds second time)
Pattern 3: Specific Rows Failing
Symptom: Same rows always fail, others always succeed
Likely cause: Data quality issues
- Invalid data in those rows
- Null values
- Wrong format
- Data out of range
Action: Fix data in failed rows, or add validation
Pattern 4: First N Rows Fail, Rest Succeed
Symptom: Initial batch fails, subsequent ones work
Likely cause: Rate limiting kicked in
- Exceeded limit with initial burst
- Limit reset, later rows processed
Action: Enable rate limiting proactively
Pattern 5: All Rows Fail After Time
Symptom: Column worked for days, suddenly all fail
Likely cause: External change
- Account token expired
- API key revoked
- Service changed API
- Account suspended
Action: Reconnect account, update configuration
Column Header Indicators
Column headers help you spot issues at a glance:
Column Header Status Indicators
Column headers show you the status of cells at a glance:
Click the "5 FAILED" indicator to jump to the first failed cell
Green spinning icon indicates cells are currently processing
Amber clock icon shows number of cells waiting to process
What you see:
Failed count - Red text showing "5 FAILED"
- Click to jump to first failed cell
- Quick way to find errors
Running indicator - Green spinning icon
- Shows cells are currently processing
- Normal during execution
Queued count - Amber clock with number
- Shows how many cells are waiting
- Normal when rate limiting is active
Error vs. Skipped States
Error vs. Skipped States
It's important to understand the difference between errors and skipped cells:
FAILED (Error)
SKIPPED
Key Difference: Failed means the column attempted to run but encountered an error. Skipped means the column intentionally didn't run because conditions weren't met.
Important Distinction
"Unsuccessful" ≠ "Skipped"
Unsuccessful (FAILED):
- Column tried to execute
- Execution started but encountered error
- Something went wrong during processing
- Blue badge with lightning bolt icon
Skipped:
- Column didn't try to execute
- Condition evaluated to false, OR
- Dependencies not ready
- Gray or red badge with different icons
Key difference:
- Unsuccessful = Attempted and failed
- Skipped = Never attempted (by design)
When "Errors" Are Normal
Some situations that look like errors are actually working as intended:
1. Data validation rejecting bad data
Input: Invalid email addresses
Validation fails: EXPECTED
Result: Don't process bad dataNot a problem: Working as intended
2. Conditional logic filtering rows
Condition: Only process high scores
Low score row: Skipped
Result: Not qualified for processingNot an error: Intentional filtering
3. Rate limiting protecting APIs
Status: Rate Limited (yellow badge)
Result: Cell queued, will retryNot a failure: System managing itself
Summary: Understanding Errors
You now understand errors in Taibles:
✅ What errors are: Failed execution with captured details
✅ Seven error types:
- Configuration errors (wrong settings)
- Validation errors (bad data)
- API errors (service failures)
- Timeout errors (too slow)
- Rate limit errors (too many requests)
- Permission errors (access denied)
- Logic errors (condition issues)
✅ How to recognize errors:
- "Unsuccessful" badges with lightning bolt
- Column header fail counts
- Error details in sidebar
✅ What gets captured:
- Error title and description
- Timestamp
- Stack trace
- HTTP details (for API errors)
- Input data context
✅ Common error patterns:
- All rows failing → Configuration issue
- Random failures → Temporary service issues
- Specific rows → Data quality issues
- First batch fails → Rate limiting
- Sudden failures → External changes
✅ Error vs. Skipped: Unsuccessful = tried and failed, Skipped = intentionally not run
Next Steps
Now that you understand errors, Section 11.2 will show you:
- Step-by-step debugging workflow
- How to diagnose root causes
- Common errors and their solutions
- How to fix and retry failed cells
Let's learn to debug! 🔍