Standard HTTP Status Codes With Special Meanings For imps And Their Agents
When a web page or a mobile app attempts to communicate with a device’s agent, it does so using the standard HTTP mechanism. Errors arising from this process will be returned as a status code, of which there are are many, pre-defined values. Wikipedia provides a list of these generic codes.
A number of these, however, have particular meanings in the context of agent communications. If your web page or app is having difficulty exchanging data with an agent, a knowledge and understanding of these specific codes may help you determine the cause of the problem, and arrive at a solution to it.
The table below lists standard HTTP response codes which have specific meanings in the context of communications with imp agents. Codes beginning with the number 4 will be automatically generated by the Electric Imp impCloud™ those starting with a 5 will be generated by the web browser or mobile OS’ HTTP sub-system.
If the statuscode is between 0 and 99, there was an error sending the request. Such errors are currently the same as libcurl error messages. For instance, statuscode == 3 means that the URL was malformed, and statuscode == 6 means that the hostname wouldn’t resolve. However, this may change in the future, so don’t write agent code that depends on particular values having particular meanings.
The agent may also send these codes, using the imp API method httpresponse.send(). This method takes two parameters: in integer for the status code to be sent, and a string containing an appropriate description of the status. Your code may send unique strings to tune standard HTTP response codes to your application. All HTTP requests sent to your agent should be completed with a call to httpresponse.send() which also closes the connection between app or website and agent.
Please see the Developer Guide ‘Effective Internet-agent-device Communication’ for an in-depth discussion of the best practices to adopt when managing communications between apps, agents and devices.
Code | Meaning | Description | Suggested Solution |
| 403 | Agent restarting | Generically, an “access forbidden” code, 403 here indicates that the agent is in the process of restarting and so unable to handle incoming HTTP requests as the present time. | Wait a moment and try to send the request to the agent again. |
| 404 | No HTTP handler/ agent offline | This is the standard HTTP “not found” code for a missing resource. In the case of the imp, it indicates that the agent you are communicating with has no HTTP request handler function, that such a function has not been registered with the agent, or that the agent is no longer running. | Agents continue to run when a device goes offline. However, if the device has been offline for a period of more than 30 days, its agent will be shut down. See the API documentation to learn how to write and register a suitable HTTP request handler. See also The Interactive imp. |
| 413 | Request size too large | The Electric Imp impCloud currently imposes a maximum size of 1MB* for standard developer agents, including code, any data the agent requires and incoming HTTP requests. Your app or web page will receive this code if your request exceeds the available storage after the agent has taken as much of the 1MB as it needs. | Check the size of the HTTP request your app or web page is making. If necessary, split the data across multiple requests. Consider whether you are sending more data that the agent requires. Commercial users who require more than 1MB of agent space should contact sales@electricimp.com |
| 429 | Rate limit exceeded | You are making too many HTTP requests to the agent too quickly. The Electric Imp impCloud currently* accepts no more than ten requests each second, adding them to a pool of up to 20 simultaneously open connections. Once there are 20 open connections, no more requests will be accepted until older ones are closed. | Consider if your app or web page is making more requests than it needs to, or making them too frequently. Do you have too many open connections in play? Open connections should be closed by the agent using the httpresponse.send() API call. Connections will stay open until httpresponse.send() is called. |
| 504 | Agent timeout | The agent did not respond in a timely manner. The Electric Imp impCloud automatically closes open connections after ten minutes of inactivity. | Your agent code may be spending too long processing data before returning a response: issue a suitable response using the httpresponse.send() API call before processing data, or before forwarding it to the device or to a web service. Connections will stay open until httpresponse.send() is called, so it’s important to include this call in your code. Uncaught errors may also prevent the agent from responding. |
*Electric Imp reserves the right to change these limits at any time, in its sole discretion, with or without notice, although Electric Imp will endeavor to provide Customer with notice of any such limitations described in this section.