Ghenne at 15:25, 25 February 2021

2021-02-25T15:25:40Z

← Older revision		Revision as of 15:25, 25 February 2021
Line 1:		Line 1:
	As much as we'd like to avoid errors, they happen from time to time. When making asynchronous calls using ~~Volt~~'s [https://docs.voltcloud.io/client/ client library] the callbacks are always of the form: <code>callback(error, data)</code>. If <code>error</code> is [https://developer.mozilla.org/en-US/docs/Glossary/Truthy truthy] it means an error has occurred while making your request. Here are some tips for understanding exactly what has gone wrong.		As much as we'd like to avoid errors, they happen from time to time. When making asynchronous calls using VoltServer's [https://docs.voltcloud.io/client/ client library] the callbacks are always of the form: <code>callback(error, data)</code>. If <code>error</code> is [https://developer.mozilla.org/en-US/docs/Glossary/Truthy truthy] it means an error has occurred while making your request. Here are some tips for understanding exactly what has gone wrong.

	== The Error Object ==		== The Error Object ==
Line 29:		Line 29:
	</syntaxhighlight>		</syntaxhighlight>

	If the [https://docs.voltcloud.io/api/ ~~Volt~~ API] is reachable and responds with an error, an additional parameter is added to the error object: <code>status</code>. If <code>error.status</code> is defined, it will be set to the HTTP status code returned by the API. This value can be useful for debugging or logging.		If the [https://docs.voltcloud.io/api/ VoltServer API] is reachable and responds with an error, an additional parameter is added to the error object: <code>status</code>. If <code>error.status</code> is defined, it will be set to the HTTP status code returned by the API. This value can be useful for debugging or logging.

	== The Data Object ==		== The Data Object ==

	For nearly all API errors, ~~Volt~~ returns an additional data object that gives you more specific information about what has caused the error. At a minimum that object will be of this form:		For nearly all API errors, VoltServer returns an additional data object that gives you more specific information about what has caused the error. At a minimum that object will be of this form:

	<syntaxhighlight lang="json">		<syntaxhighlight lang="json">
Line 76:		Line 76:
	== Extended Error Data ==		== Extended Error Data ==

	Certain types of ~~Volt~~ errors include additional information in their data object.		Certain types of VoltServer errors include additional information in their data object.

	=== ValidationError ===		=== ValidationError ===

Sarah: Instructions on handling various types of errors.

2017-05-26T18:12:34Z

Instructions on handling various types of errors.

New page

As much as we'd like to avoid errors, they happen from time to time. When making asynchronous calls using Volt's [https://docs.voltcloud.io/client/ client library] the callbacks are always of the form: <code>callback(error, data)</code>. If <code>error</code> is [https://developer.mozilla.org/en-US/docs/Glossary/Truthy truthy] it means an error has occurred while making your request. Here are some tips for understanding exactly what has gone wrong.

== The Error Object ==

We'll start by taking a look at the <code>error</code> parameter of the callback. If an error has occurred, it will be a standard [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error JavaScript Error] object.

The <code>error</code> parameter is always guaranteed to have a <code>message</code> attribute. In the case of network timeouts and errors, this will be the only attribute set. You might consider using an alert to display this message to the user:

<syntaxhighlight lang="JavaScript">
$volt.user.get(function (error, data) {
if (error) {
alert(error.message);
} else {
alert('Success!');
}
});
</syntaxhighlight>

<syntaxhighlight lang="basic">
Function userCallback(error, data)
If error Then
alert(error.message)
Else
alert("Success!")
End If
End Function

$volt.user.get(userCallback)
</syntaxhighlight>

If the [https://docs.voltcloud.io/api/ Volt API] is reachable and responds with an error, an additional parameter is added to the error object: <code>status</code>. If <code>error.status</code> is defined, it will be set to the HTTP status code returned by the API. This value can be useful for debugging or logging.

== The Data Object ==

For nearly all API errors, Volt returns an additional data object that gives you more specific information about what has caused the error. At a minimum that object will be of this form:

<syntaxhighlight lang="json">
{
"type": "VoltError",
"message": "Detailed description of the error."
}
</syntaxhighlight>

Generally <code>data.message</code> can be useful to display to an end user whereas <code>data.type</code> is useful for debugging or logging. We can modify our code above to display <code>data.message</code> if it's available:

<syntaxhighlight lang="JavaScript">
$volt.user.get(function (error, data) {
if (error) {
if (data) {
alert(data.message);
} else {
alert(error.message);
}
} else {
alert('Success!');
}
});
</syntaxhighlight>

<syntaxhighlight lang="basic">
Function userCallback(error, data)
If error Then
If data Then
alert(data.message)
Else
alert(error.message)
End If
Else
alert("Success!")
End If
End Function

$volt.user.get(userCallback)
</syntaxhighlight>

== Extended Error Data ==

Certain types of Volt errors include additional information in their data object.

=== ValidationError ===

A <code>ValidationError</code> occurs when the data you've passed in your request is invalid in some way. It may include an additional attribute: <code>validations</code>. If <code>validations</code> it truthy, it will be either in the form of a general validation, or a password validation.

==== General Validation Errors ====

For general validation errors, <code>error.validations.body</code> will be an object of the following form:

<syntaxhighlight lang="json">
{
"body": [
{
"value": "notanemail",
"property": "request.body.email",
"messages": [
"does not conform to the \"email\" format"
]
},
{
"property": "request.body",
"messages": [
"requires property \"password\""
]
}
]
}
</syntaxhighlight>

The above response was generated from the following invalid call: <code>$volt.auth.register('notanemail, undefined, 'does not match', callback);<c/ode>. If <code>error.validations.body</code> exists, it will be an array of objects. Each object will have at a minimum <code>property</code> and <code>messages</code> attributes. Some will also have a <code>value</code> attribute.

* <code>property</code> - the property that failed validation. You can ignore the <code>request.body</code> portion. In the case that the property is exactly equal to <code>request.body</code> it indicates a problem with the entire request.
* <code>messages</code> - an array of messages describing why validation failed.
* <code>value</code> - the value that failed validation, if applicable.

Generally, you will want to perform client side validation and not depend on only server side validation. However, the above data structure can provide valuable insight into why your requests are failing.

==== Password Validation Errors ====

For invalid passwords, <code>error.validations.password</code> is an array of messages indicating which validations were failed by the password:

<syntaxhighlight lang="json">
{
"password": [
"The password must be at least 10 characters long.",
"The password must contain at least one uppercase letter.",
"The password must contain at least one number.",
"The password must contain at least one special character."
]
}
</syntaxhighlight>

=== ConflictError ===

A <code>ConflictError</code> occurs when your request would cause a conflict, for instance if you attempt to register using an email address that's already in use. It includes an additional attribute, <code>conflict</code>, that includes an identifier of the existing object that would be in conflict. This is generally useful for debugging.

=== UnknownClientError ===

It's rare that you'll see an <code>UnknownClientError</code>. It generally means something was wrong with your request to the API. It includes an additional attribute in the data object: <code>detail</code>. This may provide additional detail as to why the error occurred.

Error handling - Revision history

Ghenne at 15:25, 25 February 2021

Sarah: Instructions on handling various types of errors.