Response Codes

This page introduces and explains the response codes returned by the Management API. Along with standard HTTP status codes, the Management API also returns a custom body, so that the clients can have a better understanding of what happened during the operation.

Success

All successful calls will return either:

200 OK

or

204 No Content

In case of 200 OK, the returned data structure is described with the respective operation.

Error

The Management API returns appropriate HTTP status codes depending on the nature of the error occurred. The table below lists all the possible codes returned:

Name Code Description
BadRequest 400 Returned when the request is in any form invalid. These errors can usually be fixed by the client by trying again with the appropriate request params/body.
Unauthorized 401 Returned during authentication or authorization. See more on Authorization and Authentication Errors below.
PaymentRequired 402 Returned when the subscription does not have the sufficient means to access a certain resource or execute a certain operation. For example, the owner account has exceeded the number of smartphone users allowed on its plan.
Forbidden 403 Returned in specific cases where the request is trying to access or act upon a resource which it has no permission for. For example, trying to bind a lock which is already bound.
NotFound 404 Returned when the resource could not be found.
InternalServerError 500 May be returned in cases where an unexpected error happened during the operation.

Authorization and Authentication Errors

During authentication and authorization, the Management API extensively uses the status code 401 - Unauthorized to express a couple of error scenarios. The table below lists when/why and most importantly, what a client should do in the event of a 401 response.

When / Why Recommended solution
Expired authentication token The client should refresh the authentication token or, if this isn't possible, restart the authentication process, thus getting a new and valid token. As authentication tokens always have a limited lifetime, this case happens regularly during normal operation and therefore needs to be handled by the client.
Invalid authentication token The client should check the authentication token which was sent to the API. Shouldn't happen during normal operation.
The authentication token does not have the necessary scope(s) for the operation Check if the token contains the necessary scopes for the called endpoint (see the Operations section in the documentation). Shouldn't happen during normal operation.

Expired authentication token

In case the API returns a 401 - Unauthorized and the client has a refresh token, it can be used to obtain a new access token. In most cases, this error is solved by this approach.

Lack of required scopes

In the event of being able to execute some operations but not others, most likely your token does not have the scope(s) required by the API. This can happen either if the missing scopes haven't been requested as part of the authentication flow and/or they haven't been assigned to the OAuth Client when the client was registered. In the latter case, please check if your OAuth Client has requested the appropriate scopes. You can do this by visiting Tapkey's OAuth Clients page. The changes made to the client will take effect immediately. Request a new token and try the failing request again.

Detailed Error Response

In case of an error, in addition to returning the HTTP status code, the Management API also returns a JSON structure in the response body, giving more information about what happened. An example of such a response is:

{
   "ErrorCode":"Duplicate",
   "ErrorMessage":"only one grant allowed per lock and user/card",
   "ErrorDetails":"",
   "UserErrorMessage":""
}

The table below shows a description of each field inside of the JSON error response.

Name Type Description
ErrorCode string The error code assigned by the API in certain specific error cases. See error codes below.
ErrorMessage string A short description of the error.
ErrorDetails string A more detailed description of the error.
UserErrorMessage string A user-friendly error message returned in specific cases. This message is localized according to the Accept-Language header in the request. If the language is not supported, the message will be returned in English.

Error messages localization

The ErrorMessage and ErrorDetails fields in the response body are not localized, and are always returned in English. The main purpose of these fields are to help troubleshoot problems. It is not advised to return these values to end users.

Error Codes

The ErrorCode field returned by the API helps in identifying the nature of the problem. Not all errors returned by the API will have a corresponding ErrorCode assigned to them. In essence, the error codes usually map to well-known invalid situations that can happen during a request.

The tables below list the current error codes which can be returned by the Management API.

Account Model Error Codes

Code Description
InsufficientAccountLevel Indicates that the current subscription does not have sufficient means to fulfil the operation.
InsufficientSmartphoneUserContingent The owner account has exceeded the number of smartphone users in use according to it's current account model.

Grant Error Codes

Code Description
Generic Indicates some generic error that cannot be specified more precisely.
Duplicate Indicates an operation trying to create a duplicate grant per lock and user.
CardCapacityExceeded The capacity of the card was exceeded.
TimeRestrictionIcalTooLarge The string of the ICAL is too large.
TimeRestrictionIcalNotSupportedByLock Indicates that the lock does not support time restrictions. A firmware upgrade could help in this case.
TimeRestrictionIcalTooComplex The time restriction ICAL is too complex. Reducing the number of restrictions may help.
TimeRestrictionIcalMalformed The ICAL string has an invalid format
TimeRestrictionIcalIllegalTimezone Indicates that the ICAL contains unsupported time zones, the events are in local time or not all events refer to the same time zone.
ProtocolVersionTooOld The grant cannot be created because it makes use of features that are not supported by the current lock protocol version. Upgrading the lock's firmware might help.

User Error Codes

Code Description
EmailAddressInUse Indicates that the user's email address is already in use by another user.
EmailNotVerified Indicates that the user's email address has not been verified.
EmailChangeNotSupported Indicates an attempt of changing the email address of a user, which is not allowed.