All errors received by Kuzzle clients are Kuzzle errors.

A Kuzzle error has the following properties:

statusintegerHTTP like status code. In most cases, will be the same as the response one.
messagetextShort description of the error
stacktextAvailable in development mode only - Kuzzle stack trace that generated the error

Clients can detect the error type based on their status and decide which action to take accordingly.


status: 400

A BadRequestError is thrown if Kuzzle was unable to process the action due to a malformed request.

BadRequestError objects can for instance be received if a mandatory parameter is missing or if its type is incorrect.


status: 500

An ExternalServiceError is thrown if Kuzzle was unable to process the action due to some external service failure (i.e. database).


status: 403

A ForbiddenError is thrown if the requested action is not authorized for the current authenticated user.


status: 504

A GatewayTimeoutError is thrown if Kuzzle is too long to respond.


status: 500

An InternalError is thrown if Kuzzle encountered a severe unknown error.


status 404

A NotFoundError is thrown if the requested resource could not be found, like, for instance, when calling document/get on a non-existing id.


status: 206

A PartialError is thrown if Kuzzle was unable to process a subset of a multi-actions requests.

A PartialError can be generated, for instance, if one or several queries inside a bulk/import request failed.

The detail of each failure can be retrieved using the errors property of the error object.

Additional properties

countintegernumber of failures encountered
errorsarray or KuzzleError objectsDetailed errors of the failed actions


status: 500

A PluginImplementationError is thrown if Kuzzle encountered a severe unknown error issued by a plugin.


status: 412

A PreconditionError is thrown if Kuzzle was not able to process the request due to an invalid state.

This error can for instance be generated when trying to create a document on a non-existing collection.


status: 503

A ServiceUnavailableError can be sent by Kuzzle proxy if no Kuzzle instance is found to process the request.


status: 413

A SizeLimitError is thrown by Kuzzle if the request size exceeds the limits defined in the proxy configuration.


status: 401

An UnauthorizedError is thrown by Kuzzle if the permissions could not be verified for the request.

Typically, an UnauthorizedError will be generated for a restricted action if the client is not authentified yet.