Error Classification & Response Mapping

Robust production systems do not simply assume a network call fails uniformly. They intercept and inspect backend exceptions, distinguishing between standard server execution errors and detailed constraint validation failures.

The integration module contains a dedicated error classification block designed to parse downstream validation dictionaries into human-readable strings.

Classifying Gateway Responses

The wrapper processes three main types of response exceptions:

1. Successful Outbound Routing (response.ok)

When the HTTP status falls within the 200-299 range, the module extracts the primary confirmation tracking token (messageId, id, or standard message) and marks the operation as true.

2. Standard Gateway Failures

If the request is rejected structurally but without deep schema error keys, the interface checks for a top-level description field (data.message or data.error) and passes it backward to the caller.

3. Nested Validation Errors (data.errors)

When the BongaTech validation handler rejects payload parameters (e.g., an unapproved sender ID string or an unsupported country code block), it returns a structured key-value validation object.

Dynamic Key-Value Flattening Architecture

To prevent structural nested arrays from bloating application logging views, the engine iterates over the runtime error dictionary dynamically. It matches each validation key against its array of violation notes, normalizes string arrays, and formats them into a single delimited summary block:

typescriptCopy
let errorMsg = data.message || data.error || '';
if (data.errors && typeof data.errors === 'object') {
  const detailedErrors = Object.entries(data.errors)
    .map(([field, msgs]) => `${field}: ${Array.isArray(msgs) ? msgs.join(', ') : String(msgs)}`)
    .join('; ');
  errorMsg = errorMsg ? `${errorMsg} (${detailedErrors})` : detailedErrors;
}

Response Processing Map

The following table outlines how upstream responses map to internal output values:

Logging & System Diagnostics

Every time a network response falls outside the successful response.ok range, the integration logs a deep diagnostic payload to standard error stream paths (console.error). This log includes the HTTP status, compiled error messages, parsed response records, target phone digits, and the sender profile metadata:

typescriptCopy
console.error('[BongaTech SMS Error] Failed API response:', {
  status: response.status,
  error: errorMsg,
  data,
  phone: formattedPhone,
  sender: senderId
});