Being Friendly to our API
When creating an application that will use our API, please consider that your message may not go through for various reasons. We may be having temporary technical difficulties, your application might have exceeded its
monthly quota, or the user you are sending to may have deactivated their account.
The key to being friendly to our API is to pay attention to how it responds:
- If we issue a 200 HTTP response and the status parameter in the JSON/XML body is 1, your notification has been received and queued. Well done.
- If we issue a 4xx HTTP response, or the status parameter is not 1, your input was invalid. Either your application is over its quota, your token is invalid, a user is no longer active, you are not sending a required parameter, etc. Parse the JSON/XML response, noting the errors array if present, and take the appropriate response for your type of message. The important part is that repeating your same request will not work, no matter how many times you retry it. Your input needs to be changed, you need to purchase additional message capacity for your application, or you need to stop retrying.
- If we issue a 500 or any other HTTP response, you were unable to connect to our API, or you did not get a reply, it means we are having temporary problems. You can repeat your same request again, but no sooner than 5 seconds from your last request. If we're having temporary difficulties, flooding our servers with repeated requests will just make the problem worse for everyone.
Your application should implement basic rate limiting. Do not send more than 2 concurrent HTTP requests (TCP connections) to our API, or we may do rate limiting on our side which may cause timeouts and refused connections for your IP. To speed up multiple requests, you should send each request in sequence over the same TCP connection using HTTP keep-alive to avoid the overhead of a new TCP connection and TLS negotiation.
If your application fails to act in a sane manner and sends many failed requests that result in 4xx responses within a few minutes, your IP will be automatically blocked for a temporary period. This period is automatically extended if your IP continues to send bad requests after being unblocked.