Error handling

Onur Akpolat edited this page Oct 20, 2016 · 4 revisions

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
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.