Responses & Errors

All MessageSmart API responses follow a consistent format to make error handling predictable and straightforward.

Response Structure

Every API response includes a success boolean field:

• success: true — Request completed successfully, check the data field
• success: false — Request failed, check the error field for details

Success Response (200 OK)

When a request succeeds, you’ll receive:

{
  "success": true,
  "data": {
    // Response payload varies by endpoint
  }
}

Example: Text message success

{
  "success": true,
  "data": {
    "messaging_product": "whatsapp",
    "contacts": [
      {
        "input": "+31612345678",
        "wa_id": "31612345678"
      }
    ],
    "messages": [
      {
        "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA"
      }
    ]
  }
}

Common data fields:

• data.messaging_product — Always "whatsapp"
• data.contacts — Array of contact information
• data.messages — Array of sent message IDs (useful for reactions and tracking)

Error Response Format

When a request fails, the response includes an error object:

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable error description",
    "httpStatus": 400,
    "details": null
  }
}

Error object fields

HTTP Status Codes

MessageSmart API uses standard HTTP status codes:

Common Error Types

Authentication Errors (401)

See the Authentication page for detailed authentication error responses:

• api_key_missing
• api_key_invalid
• api_key_expired
• api_key_revoked

Validation Errors (400)

Returned when your request is missing required fields or contains invalid data.

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "whatsAppBusinessPhoneNumberId or whatsAppBusinessId is required",
    "httpStatus": 400,
    "details": null
  }
}

Common causes:

• Missing required fields (to, body, whatsAppBusinessId, etc.)
• Invalid field values (e.g., malformed phone numbers)
• Empty or null values where data is required

Solution: Check the error message, verify your request payload matches the endpoint requirements.

Rate Limiting & Quota Errors (429)

Quota Exceeded

{
  "success": false,
  "error": {
    "code": "api_key_quota_exceeded",
    "message": "API key quota has been exceeded.",
    "httpStatus": 429
  }
}

You’ve reached your daily or monthly quota limit.

Solution: Wait for your quota to reset or contact support to upgrade your plan.

Rate Limit Exceeded

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again later.",
    "httpStatus": 429
  }
}

You’re sending requests too quickly.

Solution: Implement exponential backoff or check the Retry-After response header to know when to retry.

Default rate limit: 60 requests per minute per API key.

WhatsApp Provider Errors (502)

Returned when the message fails at the WhatsApp/Meta provider level.

{
  "success": false,
  "error": {
    "code": "WHATSAPP_SEND_FAILED",
    "message": "Failed to send WhatsApp text message.",
    "httpStatus": 502,
    "details": {
      "provider": "meta",
      "raw": {
        // Provider-specific error details
      }
    }
  }
}

Common causes:

• Invalid WhatsApp Business credentials
• Recipient phone number not registered on WhatsApp
• WhatsApp API rate limits or service issues
• Message template violations

Solution: Check the details.raw object for provider-specific error information. Verify your WhatsApp Business configuration and recipient details.

Server Errors (500)

Unexpected internal errors.

{
  "success": false,
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred.",
    "httpStatus": 500
  }
}

Solution: Retry the request. If the problem persists, contact MessageSmart support with the error details and timestamp.

Error Handling Best Practices

Example: JavaScript/TypeScript

const response = await fetch(
  "https://api.messagesmart.nl/api/v1/whatsapp/messages/text",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.MESSAGESMART_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      whatsAppBusinessId: "123456789012345",
      whatsAppBusinessPhoneNumberId: "106540352242922",
      to: "+31612345678",
      body: "Hello 👋",
    }),
  }
);
 
const json = await response.json();
 
if (!json.success) {
  // Handle specific error codes
  switch (json.error.code) {
    case "api_key_quota_exceeded":
      console.error("Quota exceeded. Upgrade your plan or wait for reset.");
      break;
    case "rate_limit_exceeded":
      console.error("Rate limit hit. Slow down requests.");
      break;
    case "validation_error":
      console.error("Invalid request:", json.error.message);
      break;
    default:
      console.error("API error:", json.error.code, json.error.message);
  }
  
  throw new Error(`${json.error.code}: ${json.error.message}`);
}
 
// Success! Process the data
console.log("Message sent:", json.data.messages[0].id);

Need Help?

If you encounter errors you can’t resolve:

1. Check this documentation for error code explanations
2. Review your request payload and authentication
3. Verify your WhatsApp Business configuration
4. Contact MessageSmart support with:
   • Error code and message
   • Timestamp of the failed request
   • Relevant request details (without sensitive data)