Skip to content

Response Codes

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


All successful calls will return either:

200 OK


204 No Content

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


The Web APIs return 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.
Conflict 409 The request wasn't executed because the desired state is already present or the entity was modified in a simulatnous request.
InternalServerError 500 May be returned in cases where an unexpected error happened during the operation.

Authorization and Authentication Errors

During authentication and authorization, the Tapkey Web APIs extensively use 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 Tapkey Web APIs also return a JSON structure in the response body, giving more information about what happened. An example of such a response is:

   "ErrorMessage":"only one grant allowed per lock and user/card",

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.

Retrying a failed request

In case of an error response, before running a request retry, it is required to evaluate if it is needed in the specific scenario. This can be decided based on the response code and following table will explain when it makes sense.

Name Response code Retry Description
BadRequest 4xx No Request is invalid and it makes no sense to retry it without changing the request params or body.
Unauthorized 401 No Authentication or authorization error. Retry will return the same result. Depending on the case, reauthentication might be needed.
Forbidden 403 No Permissions error. Retrying makes sense only after permissions have been updated.
Conflict 409 Depends In case of concurrency issues, retry is recommended, but applying an exponential backoff strategy is required.
InternalServerError 500 Yes Internal sever error. Something has gone wrong on the server and request retry is recommended, but applying an exponential backoff strategy is required.

Implement exponential backoff

When retrying a request always implement an exponential backoff technique to avoid generation of an excessive load on the Tapkey backend. Exponential backoff basically refers to a technique where an exponentially growing delay is inserted between individual retry attempts.