Troubleshooting
Diagnose failed requests and unexpected messaging outcomes.
Start with the Response
Capture the HTTP status, error body, request time, and relevant message or execution identifier. Redact API keys, webhook secrets, and customer data from shared logs.
| Symptom | Check |
|---|---|
400 | Required fields, country code, JSON types, batch size, and duplicate contacts in a bulk request |
401 | The x-api-key header and the key value |
403 | Brand scope and permission to access the resource |
404 | Resource ID, selected brand, or workflow family/definition |
422 | Consent transition or workflow validation errors described in the response |
429 | Slow the request rate; honor Retry-After if supplied |
Timeout or 5xx | The operation may have been accepted; reconcile before retrying sends or workflows |
Message Accepted but Not Received
Acceptance and delivery are separate. Check status webhooks, the selected recipient number, brand sender readiness, recipient capability, and suppression. Where a failure event contains failureDetails, preserve it with the message record.
Contact Does Not Receive a Campaign
Confirm that the contact is active, has marketingConsent: OPTED_IN, and belongs to the campaign's selected audience. Importing or creating a contact alone does not grant consent. An archived or opted-out contact is not made eligible by adding tags.
Webhook Does Not Reach the Expected URL
Check the brand's URL, payload version, and authentication headers. Also inspect test-phone overrides. Confirm your receiver is publicly reachable over HTTPS and accepts the configured authentication. Review response status and logs on both sides.
Batch Rejected
Contact bulk upserts allow 100 records; workflow batches allow 25 executions. These are separate limits. Split inputs accordingly and inspect per-item contact results.
Get Help
Contact your Smobi representative with the endpoint, time, sanitized error, and message or execution ID. Never send your API key or webhook secret.