Error Handling

All errors received by Kuzzle clients are Kuzzle Errors.

A Kuzzle Error has the following properties:

property type description
status integer An HTTP style status code. In most cases, will be the same as the response status.
message text A short description of the error
stack text Available in development mode only - The stack trace that generated the error

Clients can detect the error type based on the status and process the error accordingly.

Common errors

All Kuzzle requests can return one of the following errors:


Since Kuzzle 1.0.0

status: 400

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

A BadRequestError can occur if a mandatory parameter is missing or if its type is incorrect.


Since Kuzzle 1.0.0

status: 500

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


Since Kuzzle 1.0.0

status: 403

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


Since Kuzzle 1.0.0

status: 504

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


Since Kuzzle 1.0.0

status: 500

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


Since Kuzzle 1.0.0

status: 500

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


Since Kuzzle 1.0.0

status: 503

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

Specific errors

These errors are specific to controller actions.
Check controllers documentation.


Since Kuzzle 1.0.0

status 404

A NotFoundError is thrown if the requested resource could not be found (e.g. a document is requested with a non-existing id).


Since Kuzzle 1.0.0

status: 206

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

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 in the errors property of the error object.

Additional Properties

property type description
count integer The number of failures encountered
errors array of objects The list of failed actions


Since Kuzzle 1.0.0

status: 412

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

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


Since Kuzzle 1.0.0

status: 413

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


Since Kuzzle 1.0.0

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 or user has not authenticated.