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.

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 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 on portal.tapkey.io. 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:

{
   "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.

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.