Error Handling Patterns

Overview

Proper error handling ensures your document generation workflows are resilient and provide meaningful feedback when issues occur. This page explains the categories of errors you may encounter, why they happen, and the architectural patterns you should use to handle them effectively.

Tip

For step-by-step solutions to specific problems, see the Troubleshooting Guide. For detailed error code listings, see the Error Codes reference.

---

Error Categories

Build a Doc errors fall into distinct categories, each with different causes and appropriate responses. Understanding these categories helps you design workflows that handle failures gracefully.

Client Errors (4xx)

Client errors indicate a problem with the request itself. These are not retryable without fixing the underlying issue.

Code	Name	What It Means
400	Bad Request	The request format or parameters are invalid - typically a template syntax error or malformed data payload.
401	Unauthorised	The API key is missing, incorrect, or revoked. The request cannot be authenticated.
403	Forbidden	The API key is valid but the subscription lacks permission for the requested action or has exceeded quota.
404	Not Found	The requested action or resource does not exist. Usually a misspelled action name or incorrect endpoint.
429	Too Many Requests	The request rate has exceeded the allowed limit for your subscription tier.

Server Errors (5xx)

Server errors indicate a transient problem on the Build a Doc service side. These are typically retryable.

Code	Name	What It Means
500	Internal Server Error	An unexpected error occurred during processing. May be caused by edge-case inputs.
502	Bad Gateway	A gateway or proxy between your request and the service failed. Usually resolves on retry.
503	Service Unavailable	The service is temporarily unavailable, often due to maintenance or high load.
504	Gateway Timeout	The request took too long to process. Often caused by very large or complex documents.

Template Errors

Template errors occur when template syntax is invalid or data binding fails at runtime. These are not retryable - the template or data must be corrected.

Common causes include:

• Syntax errors - Missing closing tags (>>, <</foreach>>, <</if>>)
• Invalid paths - Property names that don’t exist in the data source or have typos
• Type mismatches - Using a string value where a number is expected (e.g., in arithmetic)
• Null values - Accessing properties that are missing or null without safe access operators

Connection and Network Errors

Network errors occur outside of the Build a Doc service itself, typically caused by:

• Corporate firewalls blocking outbound HTTPS to Build a Doc endpoints
• Proxy configuration not allowing the connector to reach external services
• DNS resolution failures preventing endpoint discovery

These require infrastructure changes (firewall rules, proxy configuration) rather than code fixes.

---

Retry Strategies

Not all errors should be retried. Retrying a client error (e.g., 401) will always fail again. Retrying a server error (e.g., 503) may succeed once the service recovers.

When to Retry

Error Type	Should Retry	Strategy
429 Rate Limit	Yes	Exponential backoff
500 Server Error	Yes	Fixed delay, limited attempts
502/503 Gateway	Yes	Exponential backoff
504 Gateway Timeout	Yes	Exponential backoff
400 Bad Request	No	Fix input and resubmit
401 Unauthorised	No	Fix API key
403 Forbidden	No	Check subscription/permissions
Template Error	No	Fix template

Exponential Backoff

For transient errors (5xx, 429), use exponential backoff to give the service time to recover without overwhelming it with repeated requests:

1. First retry: Wait 1 second
2. Second retry: Wait 2 seconds
3. Third retry: Wait 4 seconds
4. Fourth retry: Wait 8 seconds
5. Fifth retry: Wait 16 seconds
6. Give up after 5 attempts

This pattern doubles the wait time between each attempt, balancing recovery time against responsiveness.

---

Power Automate Error Handling Architecture

Power Automate provides built-in mechanisms for implementing robust error handling in your Build a Doc workflows.

Configure Run After

The “Configure run after” feature controls when actions execute based on the outcome of previous actions.

Setup:

1. Add a parallel branch after the Build a Doc action
2. Click the … menu → Configure run after
3. Select the conditions you want to handle:
   • is successful
   • has failed
   • is skipped
   • has timed out

Example - Parallel Error Branch:

Build a Doc Action
├── [Success path] Create file in SharePoint
└── [Failure path] Send error notification email

Scope for Try-Catch

Use Scope actions to group related actions and handle errors at the group level. This mirrors the try-catch pattern from traditional programming.

Pattern:

Scope: Try
├── Build a Doc Action
├── Create File
└── Send Email

Scope: Catch (Configure run after: has failed)
├── Compose: Error details
├── Send email: Error notification
└── Terminate: Failed

Setup Steps:

1. Add a Scope action, rename to “Try”
2. Add your Build a Doc actions inside the Try scope
3. Add another Scope after Try, rename to “Catch”
4. Configure Catch to run after Try “has failed”
5. Add error handling actions inside Catch

See Handle Errors in Flows for complete instructions with examples.

Accessing Error Information

Use these Power Automate expressions to access error details in your error handling branches:

Error Message:

result('Build_a_Doc_Action')?['error']?['message']

Full Error Object:

result('Build_a_Doc_Action')?['error']

Status Code:

result('Build_a_Doc_Action')?['statusCode']

Body/Output:

result('Build_a_Doc_Action')?['outputs']

---

Inline Error Display

Build a Doc supports inline error display for template debugging. When enabled, template errors appear directly in the output document instead of causing the action to fail.

How it works:

• Errors are embedded in the generated document at the location where they occurred
• The action completes successfully even when template errors are present
• This makes it easy to see exactly which expressions are failing and why

When to use:

• During template development and testing
• When diagnosing data binding issues

When to disable:

• In production workflows - errors should cause the action to fail so they can be caught and handled

See Debug Template Validation Errors for setup instructions.

---

Error Handling Best Practices

1. Validate inputs - Check template and data before calling the Build a Doc action. Use Compose or Parse JSON to verify payloads.
2. Enable inline errors during development - See exactly where template expressions fail without breaking the flow.
3. Implement retries for transient failures - Use exponential backoff for 5xx and 429 errors.
4. Log errors - Record error details (status code, message, request ID) for troubleshooting and audit trails.
5. Notify on failure - Alert appropriate parties via email or Teams when errors occur in production.
6. Test edge cases - Verify behaviour with missing data, empty arrays, null values, and large payloads.

---

Related Topics

• Troubleshooting Guide
• Error Codes Reference
• Handle Errors in Flows
• Debug Template Validation Errors
• Scalability and Performance
• Limits and Quotas