{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Error Handling","description":"Complete developer documentation for the eCommunicate Omnichannel platform. WhatsApp Cloud, WhatsApp Lite, SMS, Live Chat, and Conversations APIs. Send messages, manage templates, configure webhooks, and build customer engagement at scale.","siteUrl":"https://docs.ecommunicate.co.za","keywords":["eCommunicate API","WhatsApp Business API","SMS API","omnichannel messaging","WhatsApp templates","messaging platform","South Africa messaging API"],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"error-handling","__idx":0},"children":["Error Handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All eCommunicate API errors follow a consistent JSON format with standard HTTP status codes. This guide covers the error response structure, common error scenarios, and delivery failure codes."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-response-format","__idx":1},"children":["Error response format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every error response contains four fields:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"status\": \"ERROR\",\n  \"message\": \"Description of what went wrong\",\n  \"requestId\": \"c3a1f8e2-4b6d-11ee-be56-0242ac120002\",\n  \"timestamp\": \"2026-01-15T10:30:00Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"ERROR\""]}," for failed requests"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable error description"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique UUID for the request — ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["always include this when contacting support"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 8601 timestamp of when the error occurred"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"requestId"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]}," is your most valuable debugging tool. It allows the eCommunicate support team to trace your exact request through the system. Always log it and include it in support tickets."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"http-status-codes","__idx":2},"children":["HTTP status codes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OK"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request succeeded"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Process the response"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Accepted"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Message queued for delivery"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Track delivery via webhooks or reports"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bad Request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Malformed request or missing required fields"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validate your request payload"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unauthorized"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or invalid API key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Forbidden"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Valid key but insufficient permissions"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contact support about account permissions"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not Found"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Endpoint or resource does not exist"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify the URL and resource ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Too Many Requests"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit exceeded"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Implement exponential backoff — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/rate-limits"},"children":["Rate Limits"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Internal Server Error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server-side error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry with exponential backoff; contact support if persistent"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-error-scenarios","__idx":3},"children":["Common error scenarios"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"400-bad-request","__idx":4},"children":["400 Bad Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The most common error. Check these causes:"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Invalid Parameters"},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Missing required fields (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sender"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["messages"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["templateName"]}," for notifications)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Invalid ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["messageType"]}," value — must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOTIFICATION"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHAT"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONVERSATION"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Template body has ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{{n}}"]}," placeholders but no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["body"]}," component provided"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Invalid phone number format when addressing by phone — international format, leading ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+"]}," optional, no leading ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}," (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+27..."]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["27..."]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel"]}," field not set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WHATSAPP"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SMS"]}," on the unified endpoint"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["templateId"]}," does not match an existing approved template"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipients"]}," array, or a recipient with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["neither"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["nor"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]}," — supply at least one"]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"A malformed BSUID fails as a missing recipient"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]}," is validated against the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["^[A-Z]{2}.[0-9]+$"]}," format. A malformed BSUID is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["silently ignored"]},", so a recipient sent with only a bad ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]}," (and no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]},") fails as though it had no recipient at all — the error won't mention the BSUID. Double-check the BSUID format before sending phone-less recipients."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"401-unauthorized","__idx":5},"children":["401 Unauthorized"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":["Fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API key missing from header"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: YOUR_API_KEY"]}," to every request"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API key was regenerated"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use the new key — old keys are permanently invalidated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API key is malformed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify the key is a valid UUID"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"403-forbidden","__idx":6},"children":["403 Forbidden"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":["Fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Insufficient permissions"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contact support to verify your account role and permissions"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wrong client context"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You may be attempting to access resources belonging to a different client"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"404-not-found","__idx":7},"children":["404 Not Found"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":["Fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Incorrect endpoint URL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Double-check the path against the API Reference"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid resource ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify the template, webhook, conversation, or ticket ID exists"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"message-delivery-failures","__idx":8},"children":["Message delivery failures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a message is accepted (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]},") but fails to deliver, the failure is reported via ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/webhooks"},"children":["webhooks"]}," (in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["statusUpdateURL"]}," payload) or the Message Reports API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"delivery-failure-codes","__idx":9},"children":["Delivery failure codes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Recommended action"},"children":["Recommended action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify the phone number format and that it's a real number"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["22"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Blacklisted number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The recipient has been blacklisted — check your blacklist settings"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["23"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Blocked number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The recipient has blocked your number"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["54"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Non-WhatsApp number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recipient is not on WhatsApp — enable SMS fallback. SMS fallback needs a phone number, so it isn't available for a recipient addressed by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerUserId"]}," (BSUID) alone"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["56"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Failed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Generic delivery failure — check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failureReason"]}," field for details"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["58"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Duplicate message"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["This message was already sent — check your deduplication logic"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["59"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sender not connected"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["WhatsApp Lite sender is disconnected — reconnect via QR code"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["60"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["WhatsApp Lite server unavailable"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Lite server is temporarily down — retry later"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["130429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit hit"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You're sending too fast — implement throttling and backoff"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["131026"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Message undeliverable"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Meta could not deliver the message — verify the recipient and template"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["131047"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Re-engagement required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["24-hour session expired — send a template message to re-engage"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["131053"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Media upload failed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The media URL is unreachable or the file is too large"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["132000"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Template paused"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your template has been paused due to quality issues"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["132001"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Template disabled"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your template has been permanently disabled"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting-flowchart","__idx":10},"children":["Troubleshooting flowchart"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this decision tree when a message fails:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check the HTTP status code"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4xx"]}," → Fix the request (see scenarios above)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}," → Retry with exponential backoff"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]}," → Message was accepted; check delivery status below"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check delivery status"]}," via webhook or Message Reports API"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELIVERED"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["READ"]}," → Success"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," → Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failureCode"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failureReason"]}]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check the failure code"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Codes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["54"]}," → Phone number issue"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Codes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["22"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["23"]}," → Recipient blocked/blacklisted"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Codes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["59"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["60"]}," → WhatsApp Lite connection issue"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Codes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["130xxx"]}," → Meta Cloud API issue"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Codes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["132xxx"]}," → Template issue"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["If still stuck"]}," → Contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:support@ecommunicate.co.za"},"children":["support@ecommunicate.co.za"]}," with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retry-strategy","__idx":11},"children":["Retry strategy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For transient errors (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["502"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]},"), implement exponential backoff:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"async function sendWithRetry(payload, maxRetries = 3) {\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    try {\n      const response = await sendMessage(payload);\n      if (response.status === 429 || response.status >= 500) {\n        throw new Error(`HTTP ${response.status}`);\n      }\n      return response;\n    } catch (error) {\n      if (attempt === maxRetries) throw error;\n      const delay = Math.min(1000 * Math.pow(2, attempt), 30000);\n      console.log(`Retry ${attempt + 1} in ${delay}ms: ${error.message}`);\n      await new Promise(resolve => setTimeout(resolve, delay));\n    }\n  }\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Do not retry 4xx errors"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Client errors (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]},") indicate a problem with your request. Retrying will produce the same result. Fix the request first."]}]}]},"headings":[{"value":"Error Handling","id":"error-handling","depth":1},{"value":"Error response format","id":"error-response-format","depth":2},{"value":"HTTP status codes","id":"http-status-codes","depth":2},{"value":"Common error scenarios","id":"common-error-scenarios","depth":2},{"value":"400 Bad Request","id":"400-bad-request","depth":3},{"value":"401 Unauthorized","id":"401-unauthorized","depth":3},{"value":"403 Forbidden","id":"403-forbidden","depth":3},{"value":"404 Not Found","id":"404-not-found","depth":3},{"value":"Message delivery failures","id":"message-delivery-failures","depth":2},{"value":"Delivery failure codes","id":"delivery-failure-codes","depth":3},{"value":"Troubleshooting flowchart","id":"troubleshooting-flowchart","depth":2},{"value":"Retry strategy","id":"retry-strategy","depth":2}],"frontmatter":{"title":"Error Handling","description":"HTTP status codes, error response format, delivery failure codes, and troubleshooting.","seo":{"title":"Error Handling"}},"lastModified":"2026-07-16T09:46:36.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/error-handling","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}