Error handling

When an error occurs, our API will return an appropriate HTTP status code and an error message description.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with our servers.

Client Errors

Code	Category	Description
401	Unauthorized	The supplied credentials, if any, are not sufficient to access the resource.
403	Forbidden	You don't have access to whatever it is you're asking for.
404	Not Found	The requested resource was not found on the server.
405	Method Not Allowed	The method (i.e. POST is not allowed for the resource.
406	Not Accessible	We found what you're looking for, but it can't be represented in the format you requested.
409	Conflict	You cannot create or update a resource because another resource already exists or conflicts with one you are submitting.
415	Unsupported Media Type	You did not specify the request Content-Type header to have a value of application/json.
422	Unprocessable Entity	The request looks alright, but one or more of the parameters looks a little screwy. It is possible that you sent data in the wrong format (e.g. an array where we expected a string).
429	Too Many Requests	Your application is sending too many simultaneous requests. It might be a good idea to check your Rate Limits

Server Errors

Code	Category	Description
500	Server Error	We couldn't return the representation due to an internal server error.
503	Service Unavailable	We are temporarily unable to return the representation. Please wait for a bit and try again.
504	Gateway Timeout	This means the request is taking too long. It doesn't necessarily mean that we didn't receive your request and aren't chugging away on the changes you made though, so you may want to check before retrying.

Custom Error Codes

In order to facilitate the integration, the API will reply with a custom error body. Bellow you can see an example of it:

{
  "errors":[
    {
      "code":1502,
      "message":"error while reading the application user"
    }
  ]
}

The error message is not meant to be consumed by the end-user of the application, it's purpose is to help the developer understand what happened with the request. As such, in case of an error, we recommend NOT displaying the message from the API to your users.

If you'd like to display meaningful errors, below you can see a list of the errors that we currently have in our API. This list might update over time as we improve our code and as such you should check it from time to time.

Errors are divided into sections to which they belong to as well as request errors and server errors. Request errors will be between x000 and x499 while server errors (known as internal errors) are between x500 and x999. For example: 1003 is a request error as the e-mail address is not valid while 1503 is an internal error as the user session could not be internally read by our systems.

User login error handling

As login end-points are an attack vector targeted by malicious users, our API will intentionally not respond with a clear error message whenever a login is attempted.

Existing error codes

Bellow you can find the error codes that are present in our system as of 27.11.2015

User Errors

Code	Message	Description
1001	application user not found	The user was not found in our system
1002	email address already in use	The specified e-mail address is currently in use by another user
1003	user email is not valid	The specified e-mail address is not valid
1004	user first name must be between 2 and 40 characters	User first_name field length validation failed because the field is either too short or too long
1005	user id is not valid	The ID of the user is not in a format recognized by our system
1006	user last name must be between 2 and 40 characters	User last_name field length validation failed because the field is either too short or too long
1007	user email and username are both empty	This error occurs when both email and user_name fields of our e-mail are empty.
1008	username already in use	This error occurs when the user_name field of the user is empty
1009	type at least 3 characters to search	In order to search for a user in our system you have to send at least 3 characters
1012	user username must be between 2 and 40 characters	User user_name field length validation failed because the field is either too short or too long

Internal User Errors

Code	Message	Description
1500	error while creating the application user	There was an internal error while creating an application user.
1501	error while retrieving list of application users	There was an internal error while retrieving a list of application users
1502	error while reading the application user	There was an internal error while reading an application user
1503	error while creating the application user session	There was an internal error while creating a session for a user
1504	error while deleting session	There was an error while deleting a session of a user
1505	error while reading the application user session	There was an error while reading the session of the user
1506	error while deleting all session	There was an error when trying to delete all the sessions of a user
1507	error while updating the application user session	There was an error while refreshing the user session
1508	error while updating the application user	There was an error while updating the user
1509	user ID is missing	There was an internal error and the user ID could not be created properly

Connection Errors

Code	Message	Description
2000	connection already exists	The connection between users already exists
2001	connection not found	The connection between users was not found
2002	unexpected connection type	The connection type is not supported.
2003	user is connecting with itself	The user tried to connect to itself. At this time the API does not support such a use-case.
2004	users are not connected	There are no connections between the users.

Internal Connection Errors

Code	Message	Description
2500	error while connecting the users	There was an internal error while creating the connection between the users.
2501	error while creating the connection	There was an internal error while creating the connection between the users.
2502	error while reading the connection	There was an internal error while reading the connection between the users.
2503	error while updating the connection	There was an internal error while updating the connection between users.
2504	error while retrieving list of followers	There was an internal error while retrieving the list of followers for a user.
2505	error while retrieving list of following	There was an internal error while retrieving the list of users being followed by a user.
2506	error while retrieving list of friends	There was an internal error while retrieving the list of friends for a user.

Event Errors

Code	Message	Description
3000	you must specify either a radius or a how many nearest events you want	Neither the parameter for distance or the count of how many objects should be retrieved has been specified for location searching.
3001	Location radius can't be smaller than 2 meters	The radius for a location area can't be smaller than 2 meters.
3002	event id is not valid	The event id is not a valid one.
3003	event id is already set	The event id is already set and should not be.
3004	event visibility is invalid	The event visibility level is incorrect.
3005	event visibility is missing	The event visibility level is missing.
3006	near events limits not within accepted bounds	You can request at least one event and at most 200 events when searching for events within a location.
3007	event not found	The specified event was not found.
3008	type must be between 1 and 30 characters	The event type must be between 1 and 30 characters in length.

Internal Event Errors

Code	Message	Description
3500	error while saving the event	There was an internal error while saving the event.
3501	error while reading the event	There was an internal error while reading the event.
3502	failed to read the events	There was an internal error while retrieving a list of events.
3503	error while updating the event	There was an internal error while updating an event.
3504	event is missing ID	There was an internal error and the event ID could not be created properly

Authentication Errors

Code	Message	Description
4001	authentication error	There was an authentication error.
4002	both username and email are specified	In order for the authentication to work either user_name or email fields have to be specified but not both at the same time.
4003	both username and email are empty	Both the user_name and the email fields are empty and at least one of them should have values.
4006	error while reading application credentials	There was an error while reading the application credentials.
4007	error while reading user credentials	There was an error while reading the application user credentials.
4008	invalid email address	The e-mail address is invalid.
4009	authorization method not supported	The authorization method is invalid.
4010	password is empty	The password field is empty.
4011	different passwords	The password value doesn't match the stored password value.
4012	session token mismatch	The provided session token does not match the expected session token.
4013	session token missing from request	The session token is missing from the request.

Server Errors

Code	Message
5000	image url is not valid
5001	malformed json received
5002	User-Agent header must be set
5003	Content-Length header is invalid
5004	Content-Length header missing
5005	Content-Length header size mismatch
5006	Content-Type header mismatch
5007	Content-Type header empty
5009	No known search terms supplied
5010	Invalid float number
5011	Payload too big
5012	Empty request body