🧩 Custom Error Handling & Retry Framework for SuiteScript Integrations

Introduction

Even the best-written NetSuite integrations fail occasionally — APIs time out, governance limits hit, or third-party services go down.
Instead of manually checking logs, you can build a Custom Error Handling Framework that captures every failure, logs it, and automatically retries based on rules.

This tutorial will walk you through creating a robust, reusable error-handling layer used in real-world integrations with Boomi, Shopify, and Salesforce.

💡 Why a Centralized Error Framework?

🧱 Step 1: Create Custom Record — “Integration Error Log”

Name: Integration Error Log
ID: customrecord_error_log

✅ Add permissions for Integration Admin or Developer roles only.

⚙️ Step 2: Centralized Error Handling Utility

Create a shared module you can import into any SuiteScript.

/**
 * @NApiVersion 2.1
 * @NModuleScope Public
 */
define(['N/record', 'N/log'], (record, log) => {

    const logError = (source, recordType, recordId, errorObj, scriptType) => {
        try {
            const errRec = record.create({ type: 'customrecord_error_log', isDynamic: true });
            errRec.setValue('custrecord_err_source', source);
            errRec.setValue('custrecord_err_recordtype', recordType);
            errRec.setValue('custrecord_err_recordid', recordId);
            errRec.setValue('custrecord_err_message', JSON.stringify(errorObj.message || errorObj));
            errRec.setValue('custrecord_err_retry_status', 'Pending');
            errRec.setValue('custrecord_err_retry_count', 0);
            errRec.setValue('custrecord_err_script_type', scriptType);
            errRec.save();
        } catch (e) {
            log.error('Error Logging Failure', e);
        }
    };

    return { logError };
});

✅ Usage: Import this module into any Map/Reduce, RESTlet, or Scheduled Script to catch and record errors.

🧠 Step 3: Add Try/Catch Blocks with Error Logging

Example in a Map/Reduce Script:

try {
   // process invoice
   record.submitFields({ type: 'invoice', id: invId, values: { memo: 'Processed' } });
} catch (e) {
   errorHandler.logError('Boomi', 'invoice', invId, e, 'Map/Reduce');
}

Every exception is automatically logged to your Integration Error Log.

🔄 Step 4: Automated Retry Script

Create a Scheduled Script or Map/Reduce to re-process failed records.

/**
 * @NApiVersion 2.1
 * @NScriptType ScheduledScript
 */
define(['N/search', 'N/record', 'N/log'], (search, record, log) => {
    const execute = () => {
        const results = search.create({
            type: 'customrecord_error_log',
            filters: [['custrecord_err_retry_status', 'is', 'Pending'], 'AND', ['custrecord_err_retry_count', 'lessthan', 3]],
            columns: ['internalid', 'custrecord_err_recordid', 'custrecord_err_source']
        }).run().getRange({ start: 0, end: 50 });

        results.forEach(r => {
            try {
                const recordId = r.getValue('custrecord_err_recordid');
                // Retry logic (e.g., re-call RESTlet or re-process transaction)
                log.audit('Retrying Record', recordId);
                record.submitFields({
                    type: 'salesorder',
                    id: recordId,
                    values: { custbody_retry_flag: true }
                });
                record.submitFields({
                    type: 'customrecord_error_log',
                    id: r.id,
                    values: {
                        custrecord_err_retry_status: 'Retried',
                        custrecord_err_retry_count: '@{custrecord_err_retry_count}+1'
                    }
                });
            } catch (err) {
                log.error('Retry Failed', err);
            }
        });
    };
    return { execute };
});

✅ Retries only failed records with retry count < 3 — prevents infinite loops.

🧮 Step 5: Dashboard Monitoring (Saved Search or SuiteAnalytics)

Saved Search: Integration Error Overview

• Filters: custrecord_err_retry_status is not Success
• Columns: Source, Record Type, Record ID, Error Message, Retry Count, Last Update
• Highlighting:
  • Red → Failed
  • Yellow → Pending
  • Green → Retried

Add this to Home Dashboard for real-time tracking.

🧠 Step 6: Email / Slack Notifications

Workflow Notification (Simpler)

• Trigger: On Create (if Retry Status = “Pending”)
• Action: Send Email → Integration Team

Advanced (Slack via RESTlet)

Send Slack alert on every failed integration:

https.post({
  url: 'https://hooks.slack.com/services/T0000/B0000/XXXX',
  body: JSON.stringify({ text: `🚨 Integration Failed: ${errorMessage}` }),
  headers: { 'Content-Type': 'application/json' }
});

⚡ Step 7: Governance & Performance Tips

🧩 Real-World Framework Workflow

1️⃣ RESTlet / Script fails → Logs error in Custom Record
2️⃣ Scheduled Script scans Pending logs daily
3️⃣ Retries failed transactions (up to 3×)
4️⃣ Success → Status = Retried; Failure → Status = Failed
5️⃣ Dashboard + Email Alerts show live summary

🧰 Bonus: Custom Error Utility Snippet

Reusable utility for cleaner scripts:

function safeExecute(fn) {
    try { fn(); } 
    catch (e) { errorHandler.logError('RESTlet', 'transaction', null, e, 'Suitelet'); }
}

✅ Keeps your core code readable and error-proof.

📚 Related Tutorials

• 👉 Integration Logging & Monitoring Dashboard
• 👉 SuiteScript Security & Governance Best Practices
• 👉 NetSuite Deployment & Version Control Strategy

❓ FAQ

Q1. Can I automatically retry failed Boomi or Celigo integrations?
Yes — send retry POST requests from the Scheduled Script back to your middleware endpoint.

Q2. Can this handle RESTlet and Map/Reduce together?
Absolutely — log script type (Map/Reduce, RESTlet) and handle retries differently per type.

Q3. Can I notify users in NetSuite UI?
Yes — use a custom Portlet showing recent “Failed Integrations.”

Q4. What if error logging itself fails?
Wrap the logger in a try/catch with minimal dependencies (as above) so failure doesn’t block your main process.

🧭 Summary

With this framework, your NetSuite environment gains self-healing capability — failed transactions are captured, reviewed, and retried automatically.
Instead of reactive debugging, you get proactive stability, visibility, and accountability for every integration.

This pattern transforms NetSuite into an enterprise-grade integration platform ready for high-volume, audit-safe operations.