Unfortunately, always there is something that could go wrong while processing of API requests. Connection can be lost, token can be expired, some exception can be unhandled and so on. Stuff happens. And you must be ready to that.
Here is the complete list of responses for different types of API errors. Errors are grouped by main platform's subsystems and each error type has its own identifier.
If some request resulted in an error, than platform instance returns a response with HTTP status code not less than 400 and JSON-encoded body with an additional information about an error.
A format of request body is the following:
{
"error_id": "int, an identifier of an error",
"devel_message": "Some message for developers",
"user_message": "Some message that can be directly displayed to the user",
"docs_url": "A link to the related section in platform's documentation"
}
Regarding HTTP status codes:
- codes starting from 400 are error codes;
- codes >= 400 and < 500 indicate client-side errors;
- codes >= 500 indicate server-side errors.
This error can be thrown on POST requests. It may indicate that:
- a client application forgot to set
Content-Type
request header; - or
Content-Type
header value points to unsupported type of content.
This error indicates some issue with the client-side code and should be fixed by client's developer.
For now only one type of request content is supported and can be read: application/json
. In future additional content-types may be supported like application/xml
. Extra information about content-types in general can be found on Wikipedia and MDN.
HTTP status code: 400.
This error can be thrown on POST requests. It may indicate that:
- a passed request body is not a valid JSON, XML or other file format that was declared in
Content-Type
header; - the value of
Content-Type
header doesn't correspond to the content of request body.
This error indicates some issue with the client-side code and should be fixed by client's developer.
HTTP status code: 400.
This error can be thrown on any request. It may indicate that:
- a request was completely valid but server caught some internal error.
In this situation there is nothing to do from the client-side. Please, contact an administrator of the platform and platform's developers if needed to resolve this issue.
HTTP status code: 500.
This error can be thrown on all requests. It may indicate that:
- a request method like GET, POST, PUT and so own is not supported for this resource (URL, endpoint).
This error indicates some issue with the client-side code and should be fixed by client's developer. For the full list of available resources and corresponding HTTP methods, please take a look in ./rest_api
page of documentation.
HTTP status code: 405.
This error can be thrown on all requests. It may indicate that:
- the specified resource was deleted, moved or was not existing at all.
In case of this error please double-check the specified URL. For example, you can have a spelling error, an extra slash symbol or a missing one. If you are sure that the specified URL is valid, than it means that the corresponding resource or object was deleted. This is fine. Just be ready to that.
HTTP status code: 404.
This section is related to the errors in authorization and authentication processes.
This error can be thrown on POST requests on /auth
endpoint. It may indicate that:
- a client application forgot to pass 'username' field in request body;
- a client application passed a username that is equal to null.
This error indicates some issue with the client-side code and should be fixed by client's developer. Do not allow to user to send an empty username field.
Warning
This behaviour may be changed if 'insecure' mode will be introduced. Please, take a look in this pull request to get more information: pull#15.
HTTP status code: 400.
This error can be thrown on POST requests on /auth
endpoint. It may indicate that:
- a client application forgot to pass 'password' field in request body;
- a client application passed a password that is equal to null.
This error indicates some issue with the client-side code and should be fixed by client's developer. Do not allow to user to send an empty password field.
Warning
This behaviour may be changed if 'insecure' mode will be introduced. Please, take a look in this pull request to get more information: pull#15.
HTTP status code: 400.
This error can be thrown on POST requests on /auth
endpoint. It may indicate that:
- the user specified a non-existing username;
- the user specified an invalid password value.
This error indicates some issue from the user-side. In this case please, help to user to log into system and provide some related suggestions.
HTTP status code: 401.
This error can be thrown on all requests on protected resources. It may indicate that:
- the client application forgot to pass an
Authorization
header in HTTP request; - the value of this header is null.
This error indicates some issue with the client-side code and should be fixed by client's developer. You must to pass a non-empty authorization header while accessing to protected resources. To get more information about the authorization process, please take a look into protected_resources
section of documentation.
Warning
This behaviour may be changed if 'insecure' mode will be introduced. Please, take a look in this pull request to get more information: pull#15.
HTTP status code: 400.
This error can be thrown on all requests on protected resources. It may indicate that:
- the access token was revoked;
- the access token was invalid from the start.
This error indicates that the access token must to be renewed. In this case it is recommended to redirect user to authorization page. To get more information about the authorization process, plese take a look into protected_resources
section of documentation.
Warning
This behaviour may be changed if 'insecure' mode will be introduced. Please, take a look in this pull request to get more information: pull#15.
HTTP status code: 400.
This error can be thrown on all requests on protected resources. It may indicate that:
- the user doesn't have an access to this resource;
- the user doesn't have a permission to modify this resource;
- the specified access token doesn't permit to process this request for some other reason.
This error indicates that the user doesn't have an access to this resource for some reason. There is nothing to do from the client-side. In this situation please describe what was happened to user and help him/her to contact an administrator of platform's instance and to get a corresponding rights.
Warning
This behaviour may be changed if 'insecure' mode will be introduced. Please, take a look in this pull request to get more information: pull#15.
HTTP status code: 403.
This error can be thrown on attempts to send a command on execution to the Thing. It may indicate that:
- the
/execute
sub-resource is not available for this instance; - this instance isn't capable of command execution.
This error indicates some issue with the client-side code and should be fixed by client's developer. Do not allow to user to send any commands to the non-actuator objects.
HTTP status code: 404.
This error can be thrown on attempts to send a command on execution to the Thing. It may indicate that:
- the client application forgot to pass a
command
value in a body of HTTP request; - the value of this header is not a string (i.e. is a number, null or a value of some other type).
This error indicates some issue with the client-side code and should be fixed by client's developer. You must to pass a valid command
value while sending of commands on execution to Actuators. To get more information about the /execute
request and its format, please take a look into things_executing_commands
section of documentation.
HTTP status code: 400.
This error can be thrown on attempts to send a command on execution to the Thing. It may indicate that:
- the client application forgot to pass a
command_args
value in a body of HTTP request; - the value of the
command_args
key is not a mapping (dictionary).
This error indicates some issue with the client-side code and should be fixed by client's developer. You must to pass a valid command_args
value while sending of commands on execution to Actuators. To get more information about the /execute
request and its format, please take a look into things_executing_commands
section of documentation.
HTTP status code: 400.
This error can be thrown on attempts to send a command on execution to the Thing. It may indicate that:
- the client application forgot to pass some non-optional argument in the
command_args
field of a body of HTTP request; - the client application passed an unexpected extra (additional) command argument in the
command_args
field of a body of HTTP request; - one of the command arguments haves an invalid type;
- one of the command arguments haves an invalid value.
This error indicates some issue with the client-side code and should be fixed by client's developer. You must to pass a valid command_args
value while sending of commands on execution to Actuators. To get more information about the /execute
request and its format, please take a look into things_executing_commands
section of documentation.
HTTP status code: 400.
This error can be thrown on attempts to send a command on execution to the Thing. It may indicate that:
- the specified instance of Actuator doesn't support the requested command.
This error indicates some issue with the client-side code and should be fixed by client's developer. You must to pass the name of a command which is supported by the specified Thing instance in command
field in request body. To get more information about the /execute
request and its format, please take a look into things_executing_commands
section of documentation.
HTTP status code: 400.
There is no Placement-specific exceptions for now.
Streaming API has its own subset of errors in addition to the errors defined above. All errors with identifiers starting from 5000
and to 5999
including are considered as Streaming API-specific errors.
This error can be thrown on attempts to use a Streaming API. It may indicate that:
- the server was expected to receive a message from a client in the specified time window but such message wasn't sent.
This error indicates some issue with the client-side code and should be fixed by client's developer. In some situations server may wait a message from a client application in the specified time window (not later than X time units after some point of time). For example, the client must to send Authentication message not later than 20 seconds from the connection establishment (as defined in ./streaming_api
section of documentation). You must to send messages in the specified time windows, otherwise you will receive this (5000) error.
This error can be thrown on attempts to send a frame using a Streaming API. It may indicate that:
- the frame sent has type that is different from expected.
This error indicates some issue with the client-side code and should be fixed by client's developer. For now the only supported type of WebSocket frame is TEXT frame. TEXT frames are then parsed as JSON objects and interpreted as Streaming API Messages. You must not to use binary frames or any other frames for transferring Streaming API Messages.
This error can be thrown on attempts to send a frame using a Streaming API. It may indicate that:
- the content of the specified TEXT frame is not a JSON object.
This error indicates some issue with the client-side code and should be fixed by client's developer. For now all the messages passed via Streaming API must to be encoded as JSON objects according to the rules defined in ./streaming_api
section of documentation. You must to encode Messages as JSON objects and transfer them in TEXT WebSocket frames. Otherwise the mentioned (5002) error will be thrown.
This error can be thrown on attempts to send a message using a Streaming API. It may indicate that:
- the received message is a valid JSON object is not a valid Message object;
- some fields of Message are missing or have an appropriate type.
This error indicates some issue with the client-side code and should be fixed by client's developer. For now all the messages passed via Streaming API must to be encoded as JSON objects according to the rules defined in ./streaming_api
section of documentation. You must to encode Messages as JSON objects and transfer them in TEXT WebSocket frames. Otherwise the mentioned (5003) error will be thrown.
The name of erroneous field is specified in devel_message
field of Error message.
This error can be thrown on already opened Streaming API connections. It may indicate that:
- some client initiated a new Streaming API connection using the same access token and connected to the same Session.
This error usually indicates some issue with the client-side code and should be fixed by client's developer. In some situations, client applications keeps old connections unclosed while attempting to establish a new one. In such situations, the old connection is closed with the specified error - 5004. To avoid this error, please, close the old Streaming API connections before the new connection will be opened.
This error can be thrown on attempts to use a Streaming API. It may indicate that:
- the server was expected to receive a Control Message from a client but the message received is not a Control Message.
This error indicates some issue with the client-side code and should be fixed by client's developer. In some situations server may wait a message from a client application with the specified type: either Control Message or Data Message. To define either the received Message is Control or Data Message, the type
field is used according to the ./streaming_api
section of documentation. You must to send messages with a type, appropriate to the current situation, otherwise you will receive this (5010) error.
This error can be thrown on attempts to use a Streaming API. It may indicate that:
- the server was expected to receive a Data Message from a client but the message received is not a Data Message.
This error indicates some issue with the client-side code and should be fixed by client's developer. In some situations server may wait a message from a client application with the specified type: either Control Message or Data Message. To define either the received Message is Control or Data Message, the type
field is used according to the ./streaming_api
section of documentation. You must to send messages with a type, appropriate to the current situation, otherwise you will receive this (5011) error.
This error can be thrown on attempts to use a Streaming API. It may indicate that:
- the server was expected to receive a Message with the specified topic from a client but the topic of the received message is different from expected.
This error indicates some issue with the client-side code and should be fixed by client's developer. In some situations server may wait a message from a client application with the specified topic. You must to send messages with a topic, appropriate to the current situation, otherwise you will receive this (5020) error. To define what message topic is expected in the current situation, please refer to the ./streaming_api
section of documentation. The expected topic of a message is defined in devel_message
field of Error message.
This error can be thrown on attempts to use a Streaming API. It may indicate that:
- the server expected to find some information in a body content of received message but such information is missing or is invalid (by type or value).
This error indicates some issue with the client-side code and should be fixed by client's developer. In some situations client must to send messages with the specified type, topic and the message body content. You must to send messages with bodies as defined in the ./streaming_api
section of documentation, otherwise you will receive this (5030) error. The name of the missing or erroneous field is defined in devel_message
field of Error message.