Search Knowledge Base Articles

Find answers, guides, and documentation

API Error Codes Reference

This article is a complete reference of all machine-readable error codes returned by the MigoSMTP and Telnxo APIs. Every error response includes a string error field that identifies the specific error type — use this reference to handle errors correctly in your application code.

Error response format reminder: All API errors return a consistent JSON body with success: false, an error string code, a human-readable message, the HTTP code, and optionally a field for validation errors. Match your error handling logic against the error string — not the message, which may change between API versions.

Authentication Errors (HTTP 401 / 403)

Error Code	HTTP	Cause	Resolution
authentication_required	401	Authorization header missing from request	Add `Authorization: Bearer YOUR_KEY` header
invalid_api_key	401	API key is incorrect, malformed, or revoked	Check key value; generate a new key if revoked
api_key_expired	401	API key has passed its configured expiry date	Generate a new API key
insufficient_scope	403	Key does not have the required scope for this endpoint	Create a new key with the necessary scope
ip_not_whitelisted	403	Request IP not in the key's allowed IP list	Add the server IP to the key's whitelist

Account & Subscription Errors (HTTP 402 / 403)

Error Code	HTTP	Cause	Resolution
account_suspended	402	Subscription is suspended; invoice overdue	Pay outstanding invoice in Rackwave portal
account_expired	402	Trial or subscription has expired	Upgrade or renew subscription
quota_exceeded	402	Monthly sending quota fully consumed	Upgrade plan or wait for next billing cycle reset
daily_limit_reached	429	Daily sending limit reached for this plan	Wait until midnight (your timezone) for reset; or upgrade
hourly_limit_reached	429	Hourly sending limit reached	Wait until the next hour window; or upgrade

Validation Errors (HTTP 400 / 422)

Error Code	HTTP	Cause	Resolution
missing_required_field	422	A required request field is absent	Check the `field` property in the error response for which field is missing
invalid_email_address	422	The `to`, `from`, or `reply_to` field is not a valid email	Validate email addresses before sending; use RFC 5321 format
invalid_phone_number	422	Phone number not in E.164 international format	Format numbers as `+[country code][number]` e.g. `+919876543210`
invalid_json	400	Request body is not valid JSON	Validate JSON before sending; check for trailing commas or unescaped characters
field_too_long	422	A field value exceeds maximum allowed length	Truncate the value; check API docs for field length limits
invalid_template_id	422	The specified template ID does not exist or is inactive	Verify the template ID; ensure the template is published and active
missing_template_variable	422	A variable defined in the template has no value in the request	Provide all required template variables or define fallback values in the template
domain_not_verified	422	The `from` domain has not been verified in MigoSMTP	Complete domain verification in Dashboard → Domain Management
sender_id_not_registered	422	The Sender ID used in SMS is not registered on the account	Register the Sender ID in Telnxo → SMS → Sender IDs

Resource Errors (HTTP 404 / 409)

Error Code	HTTP	Cause	Resolution
resource_not_found	404	The requested resource ID does not exist	Verify the ID — check for typos or stale references
duplicate_resource	409	A resource with this identifier already exists	Use a different identifier or update the existing resource
duplicate_idempotency_key	409	An `X-Idempotency-Key` was reused within 24 hours	Use a new unique idempotency key for each request
resource_limit_reached	409	Plan limit reached for this resource type (domains, SMTP accounts, etc.)	Delete an existing resource or upgrade your plan

Sending / Delivery Errors (HTTP 422)

Error Code	HTTP	Cause	Resolution
recipient_suppressed	422	Recipient address or phone number is on the suppression list	Remove from suppression list if unsubscribe was in error; otherwise do not send
dnd_number	422	Phone number is registered on the DND (Do Not Disturb) registry (India)	Do not send promotional SMS to DND numbers; only transactional SMS is permitted
dlt_scrubbed	422	SMS content did not match any registered DLT template (India)	Register the exact message template on DLT and map the PE ID and Template ID
whatsapp_template_not_approved	422	WhatsApp template used in the request has not been approved by Meta	Wait for Meta approval or use a different approved template
session_window_expired	422	WhatsApp 24-hour session window has closed; template message required	Send a template message to re-open the conversation window

Rate Limit Errors (HTTP 429)

Error Code	HTTP	Cause	Resolution
rate_limit_exceeded	429	Too many API requests in the current rate limit window	Wait for the `Retry-After` seconds then retry with exponential backoff
daily_limit_reached	429	Daily message dispatch limit reached for current plan	Wait for midnight reset in your timezone; upgrade plan for higher limits
hourly_limit_reached	429	Hourly message dispatch limit reached	Queue requests and retry after the next hour window opens

Server Errors (HTTP 500 / 503)

Error Code	HTTP	Cause	Resolution
internal_error	500	Unexpected platform-side error	Retry with exponential backoff; if persistent, open a support ticket with the request ID from the response
service_unavailable	503	Platform is under maintenance or temporarily overloaded	Retry after a short delay; check the platform status page for maintenance notices
gateway_timeout	504	Upstream service (carrier, relay) did not respond in time	Retry the request; the message may or may not have been queued — check logs before retrying to avoid duplicates

Request ID for Support

Every API response includes a unique X-Request-ID header. When contacting support about an API issue, always include this value — it allows the engineering team to trace the exact request through the system logs:

X-Request-ID: req_8f3a2b1c9d4e7f0a

Next Steps

Did you find this article useful?