When working with the EasySendSMS REST API or HTTP API, it's crucial to address any challenges that arise to ensure continuous functionality. Below are detailed steps and considerations to assist you in troubleshooting potential issues that may disrupt your API integration.
Whether you are integrating our HTTP API for sending single or bulk SMS messages, using the REST API (v1) for JSON-based workflows, or connecting via SMPP for high-throughput enterprise messaging, encountering errors during development is a normal part of the integration process. This comprehensive troubleshooting guide is designed to help developers quickly diagnose and resolve the most common API issues, minimize downtime, and ensure that your SMS delivery pipeline remains stable and reliable in production environments.
The EasySendSMS SMS API gateway is built for reliability and performance, supporting global message delivery across 200+ countries and 1100+ mobile networks. However, integration issues can arise from misconfigured authentication credentials, incorrect request parameters, network-level restrictions, or encoding mismatches. The sections below address each of these scenarios in detail, providing actionable steps that developers can follow to resolve problems efficiently. For additional code examples and SDK references, visit the EasySendSMS Developer Hub.
Ensure that your HTTP request is properly authenticated using the correct API key or, for the legacy HTTP API, the correct username and password. Authentication issues are a common source of problems. Double-check that your credentials are correctly formatted and have not expired. If you're using the API key, make sure it is included in the request headers as specified in the API documentation.
Double-check that the IP address from which your API request is originating is correctly configured and whitelisted in your EasySendSMS account settings. If you have enabled IP whitelisting for added security, ensure that the IP address making the request matches one of the IPs listed in the "Whitelisted IP Addresses" section of your account. Requests from non-whitelisted IP addresses will be blocked, leading to authentication failures. It's also important to verify that your network's outbound IP address has not changed unexpectedly, as this could cause your requests to be rejected.
When an error occurs, the API will return an error code. You can refer to the EasySendSMS error code tables for both the HTTP API and the REST API to understand the specific issue indicated by the error code, whether it's related to missing parameters, invalid credentials, or service availability. By following the troubleshooting steps provided for each error code, you can effectively resolve the issue.
Make sure that all required parameters are included in your API request. Missing parameters are a common cause of API errors. Review the API documentation to confirm that you're providing all the necessary information. This includes mandatory fields like the destination number, message content, and any other parameters specified as required for the API endpoint you're using.
If you're utilizing one of the EasySendSMS SDKs, ensure that all the required dependencies are installed and properly configured. Missing or outdated dependencies can cause the SDK to malfunction, leading to errors in your API calls. Verify that your development environment meets the SDK's requirements and that all libraries are correctly referenced in your project.
If your API requests include a callback URL, confirm that it is correctly configured and accessible. The callback URL is where the API sends status updates or responses, so it must be operational and capable of receiving HTTP requests. Check for issues such as incorrect URL formatting, network restrictions, or server-side errors that might prevent the callback from functioning properly.
During testing, ensure that the phone numbers you are using are valid, active, and capable of receiving messages. Invalid or inactive numbers can cause the API to return errors or fail to deliver messages. Additionally, testing with real, live numbers in different regions can help you confirm that the API is functioning as expected across various networks and locations.
Incorrect character encoding is a frequent cause of message delivery failures and garbled text on the recipient's device. When sending standard English messages, set the message type parameter to type=0 for GSM 7-bit encoding. For messages containing non-Latin characters such as Arabic, Chinese, Korean, or Hindi, use type=1 for Unicode (UCS-2) encoding and ensure the message body is properly encoded in UTF-16BE or URI-encoded format. Review the SMS encoding and message length guide for detailed character set tables, segment calculation rules, and encoding best practices that help you avoid truncation and delivery errors.
Sender ID regulations vary significantly by country. Some destinations allow custom alphanumeric sender IDs, while others require pre-registered sender names or only permit numeric short codes and long codes. If your messages are being rejected or the sender ID is being overwritten by the carrier, check the destination country's sender ID policy in our SMS routes documentation. Using a non-compliant sender ID is one of the most common reasons for message filtering and delivery failures in international SMS marketing campaigns.
The EasySendSMS API enforces rate limits to maintain service quality for all users. The default rate limit for the Send SMS endpoint is 30 requests per second per account, while the Balance API is limited to 2 requests per minute. If your application exceeds these thresholds, the API will respond with a 429 Too Many Requests HTTP status code. Implement exponential backoff and retry logic in your code to handle rate-limited responses gracefully. For high-volume sending requirements, consider using SMPP connectivity which supports throughput of up to 500 messages per second, or contact our support team to request a higher API rate limit for your account.
All destination phone numbers must be submitted in international format without the leading plus sign, spaces, or dashes. For example, a US number should be formatted as 12345678900 (country code + number). Incorrectly formatted numbers will trigger error code 1005 (HTTP API) or 4012 (REST API) and the message will not be sent. To proactively clean your contact lists and verify that numbers are active before sending, use the HLR Lookup API or the Number Validation API to check subscriber status, network information, and porting details in real time.
If your messages are being submitted successfully but you are not receiving delivery confirmations, verify that your Webhook (DLR callback) URL is correctly configured in your account settings. The webhook endpoint must return an HTTP 200 status code and accept GET, POST, and HEAD request methods. Also ensure that your server is not blocking inbound requests from external IP addresses. Delivery reports provide critical insight into whether messages reached the handset (DELIVRD), expired due to carrier timeout (EXPIRED), or failed to deliver (UNDELIV), and are essential for monitoring the health of your messaging pipeline.
Understanding error codes is essential for fast debugging. When the EasySendSMS API returns an error, the response includes a numeric code that identifies the exact problem. Below is a quick-reference guide to the most frequently encountered error codes across both the HTTP API and the REST API, along with recommended actions for each scenario.
These codes indicate that the username, password, or API key provided in the request is invalid or missing. For the HTTP API, verify that the username and password parameters are correct. If you have set a dedicated API password that differs from your account password, ensure you are using the API-specific credentials. For the REST API, confirm that the apikey header is present and contains a valid key from your account dashboard. Regenerating your API key and updating it in your application can resolve persistent authentication failures.
These errors occur when the destination phone number is not in a valid international format or does not correspond to a real mobile subscriber. Ensure numbers follow the E.164 standard without the plus sign prefix. When sending bulk SMS with multiple recipients, an invalid number will be skipped and the remaining numbers will be processed. Use the HLR Lookup API to pre-validate numbers and remove inactive or invalid entries from your contact lists before launching campaigns, which reduces wasted credits and improves overall delivery rates.
Your account does not have enough SMS credits to complete the request. Check your current balance using the Balance API endpoint or log in to your EasySendSMS dashboard to view your credit balance. Top up your account and retry the request. For automated systems, implement a balance check before sending messages and set up low-balance alerts to avoid unexpected interruptions in your messaging workflows. Review our premium and economy route pricing to optimize your SMS spending.
A 429 Too Many Requests response means your application has exceeded the allowed number of API calls within the rate limit window. For the Send SMS endpoint, the default limit is 30 requests per second. For the Balance API, it is 2 requests per minute. Implement a queuing mechanism with exponential backoff to space out your requests. If your use case requires higher throughput, the SMPP protocol supports up to 500 messages per second and is recommended for enterprise-grade, high-volume messaging applications.
Before contacting support, work through this systematic debugging checklist to identify and resolve the most common integration issues with the EasySendSMS API. This checklist covers the full request lifecycle, from authentication through to delivery confirmation, and is applicable to both the HTTP API and the REST API (v1).
Confirm that you are sending requests to the correct base URL. The HTTP API endpoint is https://api.easysendsms.app/bulksms for sending SMS and https://api.easysendsms.app/balance for balance queries. The REST API base URL is https://restapi.easysendsms.app/v1/rest/sms/send. A common mistake is using HTTP instead of HTTPS, or targeting a deprecated or incorrect endpoint. Always use HTTPS to ensure your API credentials and message content are encrypted in transit.
For the REST API, every request must include three headers: apikey: YOUR_API_KEY, Content-Type: application/json, and Accept: application/json. Missing or incorrectly formatted headers will result in authentication failures or malformed request errors. For the HTTP API, parameters can be sent as query strings (GET) or form data (POST). Use tools like Postman or cURL to test your requests independently of your application code. You can also explore our Postman Collection for pre-built request templates.
When debugging delivery issues, start by sending a test message to a single, known-good phone number before scaling to multiple recipients. This isolates whether the problem is with the API integration itself or with specific destination numbers or routes. Verify the response contains a message ID in the format OK: {uuid}, which confirms successful submission to the carrier network. If the single-recipient test succeeds but bulk sending fails, review the bulk SMS documentation for multi-recipient formatting rules, including the 30-number-per-request limit and duplicate number handling.
After successfully submitting a message, use the message ID to track its delivery status. Configure your webhook endpoint to receive real-time delivery reports, or check the delivery status in your account dashboard. A DELIVRD status confirms the message reached the handset. If you see EXPIRED or UNDELIV statuses, the issue is typically at the carrier or destination level rather than with the API itself. Consult the SMS routes page for destination-specific delivery information and route recommendations.
Some carriers and countries apply content filtering rules that may block messages containing certain keywords, URLs, or promotional language. If your messages are being submitted successfully but not reaching recipients, review your message content for potential trigger words. Avoid using URL shorteners from untrusted domains, excessive capitalization, or spam-like language. For SMS marketing campaigns, include opt-out instructions where required by local regulations, and use branded or trusted URLs to improve deliverability and avoid carrier-level filtering.
Implement comprehensive logging for every API request and response in your application. Log the full request URL, headers, body, HTTP status code, and response body for each API call. This data is invaluable for diagnosing intermittent issues, identifying patterns in delivery failures, and providing detailed information to the EasySendSMS support team if you need to escalate an issue. Store logs with timestamps and correlate them with message IDs for efficient troubleshooting. For WordPress-based integrations, check the plugin logs as described in the WordPress plugin documentation.
Different integration methods have unique characteristics and potential pitfalls. The following guidance addresses common issues specific to each of the messaging protocols and tools supported by EasySendSMS, helping you resolve problems faster regardless of which integration path you have chosen.
The HTTP API supports both GET and POST methods for sending SMS. Common issues include URL encoding problems with special characters in the message body, missing required parameters, and using the account password instead of the dedicated API password. When sending Unicode messages, ensure the text is encoded in UTF-16BE hex format and the type parameter is set to 1. For URL-encoded Unicode, use proper percent-encoding of the UTF-8 byte sequence. Always URL-encode the message text when using GET requests to prevent parsing errors caused by special characters such as ampersands, equals signs, or spaces.
The REST API (v1) requires all requests to use the POST method with a JSON body. A common mistake is sending form-encoded data instead of raw JSON, or omitting the Content-Type: application/json header. Ensure your request body is valid JSON by testing it with a JSON validator before sending. The REST API does not support GET requests for sending SMS. If you receive a 405 Method Not Allowed error, verify that your HTTP client is configured to send POST requests. For bulk sending, the to field accepts comma-separated numbers as a string within the JSON payload.
SMPP integration requires IP whitelisting, TLS encryption via port 2778, and correct bind credentials (system_id and password). If your SMPP client cannot connect, verify that your IP address has been added to the EasySendSMS firewall, that your client supports TLS tunneling, and that the system_id and password match your account configuration. Set the enquire_link interval to 30 seconds to maintain the connection. If you experience throttling, check that your window size does not exceed 10 and that you are not surpassing the default throughput of 30 messages per second per bind.
If you are using the EasySendSMS WordPress plugin and messages are not being sent, first verify that the plugin is activated and that your API credentials are correctly entered in the plugin settings. Check that your WordPress hosting environment allows outbound HTTP/HTTPS connections to external APIs, as some shared hosting providers block outgoing requests. Review the WordPress debug log (wp-content/debug.log) for any PHP errors related to the plugin. Ensure that the plugin version is up to date by checking the EasySendSMS GitHub repository for the latest release.
If you have worked through all the troubleshooting steps above and the issue persists, it may be related to routing, carrier-level filtering, or account-specific configuration that requires assistance from the EasySendSMS technical team. Before reaching out, gather the following information to help our team resolve your issue as quickly as possible: your account username, the message ID(s) affected, the exact error code or HTTP status received, the destination country and phone number(s), the timestamp of the failed request, and a sample of your API request (with sensitive credentials redacted). You can submit a support request through our contact page, use the SMS Troubleshooting Wizard for guided diagnosis, or browse the Help Center for detailed articles on specific issues. Our support team is available 24/7 and typically responds within minutes.