Troubleshooting

The REST API attempts to use appropriate HTTP status codes to indicate any errors that occur while processing requests. These error responses provide detailed information on the underlying fault that can be used for debugging the error as well as providing user friendly feedback in the app.

Error Reporting

All Kinvey REST APIs return error responses using standard HTTP error codes. The error reporting is designed to make the APIs more usable—easy to implement and debug. Starting with API version 1, error responses are consistent across all REST API endpoints and use a structured format.

Every error response uses a universal dictionary to describe the error. The dictionary may see some updates from time to time but any updates are only expected to add new types of errors. Individual REST API methods will describe any behavior that diverges from the dictionary.

Error	StatusCode	Description
ParameterValueOutOfRange	400	The value specified for one of the request parameters is out of range
InvalidQuerySyntax	400	The query string in the request has an invalid syntax
MissingQuery	400	The request is missing a query string
JSONParseError	400	Unable to parse the JSON in the request
MissingRequestHeader	400	The request is missing a required header
IncompleteRequestBody	400	The request body is either missing or incomplete
MissingRequestParameter	400	A required parameter is missing from the request
InvalidIdentifier	400	One of more identifier names in the request has an invalid format
FeatureUnavailable	400	Requested functionality is unavailable in this API version
CORSDisabled	400	Cross Origin Support is disabled for this application
APIVersionNotAvailable	400	This API version is not available for your app. Please retry your request with a supported API version
BadRequest	400	Unable to understand request
BLRuntimeError	400	The Business Logic script has a runtime error. See debug message for details
InvalidCredentials	401	Invalid credentials. Please retry your request with correct credentials
InsufficientCredentials	401	The credentials used to authenticate this request are not authorized to run this operation. Please retry your request with appropriate credentials
WritesToCollectionDisallowed	403	This collection is configured to disallow any modifications to an existing entity or creation of new entities
IndirectCollectionAccessDisallowed	403	Please use the appropriate API to access this collection for this app backend
AppProblem	403	There is a problem with this app backend that prevents execution of this operation. Please contact support@kinvey.com for assistance
EntityNotFound	404	This entity not found in the collection
CollectionNotFound	404	This collection not found for this app backend
AppNotFound	404	This app backend not found
UserNotFound	404	This user does not exist for this app backend
BlobNotFound	404	This blob not found for this app backend
UserAlreadyExists	409	This username is already taken. Please retry your request with a different username
StaleRequest	409	The time window for this request has expired
KinveyInternalErrorRetry	500	The Kinvey server encountered an unexpected error. Please retry your request
KinveyInternalErrorStop	500	The Kinvey server encountered an unexpected error. Please contact support@kinvey.com for assistance
DuplicateEndUsers	500	More than one user registered with this username for this application. Please contact support@kinvey.com for assistance
APIVersionNotImplemented	501	This API version is not implemented. Please retry your request with a supported API version
APIVersionNotAvailable	501	This API version is not available for your app. Please retry your request with a supported API version
BLSyntaxError	550	The Business Logic script has a syntax error(s). See debug message for details
BLTimeoutError	550	The Business Logic script did not complete in time. See debug message for details
BLViolationError	550	The Business Logic script violated a constraint. See debug message for details
BLInternalError	550	The Business Logic script did not complete. See debug message for details

The body of the response contains information on the error. The body is JSON formatted like regular responses. Errors are guaranteed to remain unchanged when using a specific API version. Each error response body contains an HTTP response Status Code and up to three attributes: two mandatory and one optional, as described below.

• The error attribute is always present. It contains a String value representing the error type.
• The StatusCode is the HTTP response code associated with the error.
• The description attribute is always present. It contains a short user-friendly description of the error. You can pass the description up to the application user if you desire. Kinvey deserves the right to change the exact text of a description depending on developer feedback.
• The debug attribute is optional and exists solely to help debug the error. An app may choose to log this debug message if the application is running in debug mode. The Kinvey backend may or may not populate this attribute depending on the exact scenario encountered. The goal with this attribute is to provide useful information that will make it very easy to isolate the root cause and implement a fix.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    “error”: “InsufficientCredentials”
    “description”: “The credentials used to authenticate this request are not authorized to run this operation. Please retry your request with appropriate credentials”
    “debug”: “Please authenticate as an app End User or as the app admin using the Master secret to run this operation”
}

Error Handling

The Kinvey backend handles errors by aborting the request and immediately returning an error response to the client. Requests that result in errors because of bad client behavior can be re-attempted after fixing the underlying fault. Requests that fail because of permanent server side failures are indicated accordingly in the response. For such requests, please contact support@kinvey.com for help.

Debugging

Since all of Kinvey's libraries are built on top of Kinvey's HTTP REST API it is frequently useful to view the HTTP messages that are being sent and received. All requests to Kinvey servers are logged, and all responses, valid or not, include a X-Kinvey-Request-ID header. The request id will be helpful when emailing support@kinvey.com for a particular issue.

Mac users may wish to use WireShark or Charles.

Windows developers can use Fiddler which is the preferred tool at Kinvey.

There are a few open source and proprietary Java tools listed at Ask Ubuntu and, of course, one can always use FireBug through Firefox.

The API Console in the Kinvey console is a great resource for debugging REST API requests. You can use the API console to test any REST API request to the app's backend on Kinvey. Use REST API version 1 or higher to make use of detailed error reporting from Kinvey for isolating the root cause.