Check out v4 of the Fauna CLI
v4 of the Fauna CLI is now in beta. The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start. |
Error handling
This guide covers error handling for applications that work directly with the Fauna Core HTTP API.
You can use the Core HTTP API to:
The Fauna client drivers, Fauna Dashboard, and Fauna CLI use the Core HTTP API internally.
Error responses
Error responses from Core HTTP API endpoints contain an error
object with
the following properties:
-
code
: A Fauna-specific error code. -
message
: A human-readable error description.
The error
object can optionally include these properties:
-
abort
: A custom error message used for errors raised by theabort()
method. See Abort errors. -
constraint_failures
: An array of failures for check or unique constraints. See Constraint failure errors.
Errors response may include additional properties, such as a summary
that indicates the location of the error, if applicable:
{
"error": {
"code": "invalid_query",
"message": "invalid query: the query failed 1 validation check"
},
"summary": "error: the function `len` does not exist on string\n0: *query*:1\n |\n1 | 'foo'.len()\n | ^^^\n |\n",
...
}
You can use query tags to track Query endpoint requests that produce errors in Fauna Logs .
Error codes
Fauna error codes are part of the API contract and are safe to write programmatic logic against.
You should first handle errors based on their error code.
The table contains a non-exhaustive list of common error codes.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HTTP status codes
If an error contains an unrecognized code, you can address it according to the response’s HTTP status code. Most 4xx and 5xx errors have an associated Fauna error code.
Range | Description | |||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200-299 |
Successful request.
|
|||||||||||||||||||||||||||||||||
400-499 |
Client error
|
|||||||||||||||||||||||||||||||||
500-599 |
Server error
|
Error classification
You can create classes for Fauna errors based on their error code:
Error class | Error codes | Cause |
---|---|---|
Abort |
|
An |
Authentication |
|
One of the following:
|
Constraint failure |
|
The request’s query failed a check or unique constraint. See Constraint failure errors. The response’s |
Contended transaction |
|
The request failed due to transaction contention. |
Invalid request |
|
Bad request. The request does not conform to API specifications. |
Query check |
|
Before execution, one or more query validation checks failed. |
Query runtime |
Unhandled error codes with a 4xx HTTP status code. |
The request’s FQL query is invalid and failed during evaluation. |
Query timeout |
|
The request processing time exceeded the defined timeout. |
Throttling |
|
The request exceeded plan throughput limits. You can safely retry the request. See Throttling errors and rate limits. |
Service internal |
|
The Fauna service failed unexpectedly. |
For examples of how Fauna’s client drivers classify and handle errors, see:
-
JavaScript driver:
errors.ts
-
Python driver:
errors.py
-
Go driver:
error.go
-
.NET/C# driver:
ExceptionHandler.cs
-
JVM driver:
ErrorHandler.java
Abort errors
The FQL abort()
method lets you
intentionally return an error in an FQL query or UDF.
abort()
requires a user-defined return
value:
For example, in a UDF:
function checkout(orderId, status, payment) {
...
// Abort the query if its calls `checkout()` with a
// `status` other than `processing`.
if (status != "processing") {
// `Abort()` accepts a user-defined error message.
abort("Cannot call checkout with status other than processing.")
}
}
Abort errors use the abort
error code and include the return value in the
error.abort
property:
{
"error": {
"code": "abort",
"message": "Query aborted.",
"abort": "\"Cannot call checkout with status other than processing.\""
},
...
}
The return value is encoded to JSON using the
data format specified
in the Query HTTP API request’s X-Format
header.
Fauna’s client drivers include classes for abort errors:
-
JavaScript driver:
AbortError
-
Python driver:
AbortError
-
Go driver:
ErrAbort
-
.NET/C# driver:
AbortException
-
JVM driver:
AbortException
Constraint failure errors
Queries that fail a check or unique constraint return an error.
Constraint errors use the constraint_failure
error code and include an array
of constraint failures in the error
object’s
constraint_failures
array:
{
"error": {
"code": "constraint_failure",
"message": "Failed to create document in collection `Product`.",
"constraint_failures": [
{
"paths": [],
"message": "Document failed check constraint `stockIsValid`"
}
]
},
...
}
Objects in the constraint_failures
array can also include an optional
name
property that contains the name of the failed constraint.
Fauna’s client drivers include classes for constraint errors:
-
JavaScript driver:
ConstraintFailureError
-
Python driver:
FaunaError.constraint_failures
-
Go driver:
ErrConstraintFailure
-
.NET/C# driver:
Fauna.ErrorInfo.ConstraintFailures
-
JVM driver:
ConstraintFailureException
Throttling errors and rate limits
Requests that exceed plan throughput limits return an error with a:
-
limit_exceeded
error code -
429 HTTP status code.
-
X-Rate-Limited-Ops
HTTP header. The header value indicates the operation types that triggered the error, such ascompute, `read
, orwrite
. -
stats.rate_limits_hit
property in the error response. The property’s value indicates the operation types that triggered the error.
{
"error": {
"code": "limit_exceeded",
"message": "Rate limit exceeded",
},
...
"stats": {
...
"rate_limits_hit": [
"compute",
"read",
"write"
]
},
...
}
Retrying throttling errors
You can safely retry limit_exceeded
errors. We recommend using an
exponential backoff.
Fauna’s client drivers include client configuration settings to automatically
retry limit_exceeded
errors with exponential backoff. See:
Error handling example
The following example shows how to handle errors based on error codes:
const FAUNA_SECRET = '<FAUNA_SECRET>';
async function fetchFaunaData(query, args = {}) {
try {
const response = await fetch('https://db.fauna.com/query/1', {
method: 'POST',
headers: {
'Authorization': `Bearer ${FAUNA_SECRET}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
query: query,
arguments: args
})
});
const data = await response.json();
// Check if an error object is present in the response
if (data.error) {
handleFaunaError(data.error, response.status);
} else {
console.log('Query successful:', data);
return data;
}
} catch (error) {
console.error('Request failed:', error);
}
}
// Error handling based on Fauna error codes
/**
This function contains a description of each
Fauna error codes and how to handle them.
*/
function handleFaunaError(error, statusCode) {
switch (error.code) {
/**
* An error returned by calling the FQL `abort()` function.
*/
case 'abort':
console.error('Transaction aborted:', error.message);
break;
/**
* A runtime error due to failing schema constraints.
*/
case 'constraint_failure':
console.error('Constraint failure:', error.message);
break;
/**
* Feature disabled error.
*/
case 'disabled_feature':
console.error('Feature disabled:', error.message);
break;
/**
* An error due to a deleted document.
*/
case 'document_deleted':
console.error('Document deleted:', error.message);
break;
/**
* An error due to a missing document.
*/
case 'document_not_found':
console.error('Document not found:', error.message);
break;
/**
* A type of AuthorizationError that indicates the user does not have
* privileges to perform requested operations.
*/
case 'forbidden':
console.error('Forbidden:', error.message);
break;
/**
* A type of ServiceInternalError indicates Fauna failed unexpectedly.
*/
case 'internal_error':
console.error('Internal error:', error.message);
break;
/**
* An error due to an invalid argument or query.
*/
case 'invalid_argument':
case 'invalid_computed_field_access':
case 'invalid_date':
case 'invalid_effect':
case 'invalid_id':
case 'invalid_null_access':
case 'invalid_regex':
case 'invalid_schema':
case 'invalid_time':
case 'invalid_type':
case 'invalid_write':
console.error('Invalid Error:', error.message);
break;
/**
* An error due to invalid method invocation.
*/
case 'method_not_allowed':
console.error('Method not allowed:', error.message);
break;
/**
* An error due to a null value.
*/
case 'null_value':
console.error('Null value:', error.message);
break;
/**
* Request exceeds the maximum HTTP request payload.
*/
case 'request_size_exceeded':
console.error('Request size exceeded:', error.message);
break;
/**
* Type of Authentication Error indicates invalid credentials were
* used.
*/
case 'unauthorized':
console.error('Unauthorized:', error.message);
break;
/**
* Indicates a throughput limit was exceeded
* and thus the request could not be served.
*/
case 'limit_exceeded':
console.error('Limit exceeded:', error.message);
break;
/**
* A failure due to the query timeout being exceeded.
*
* This error can have one of two sources:
* 1. Fauna is behaving expectedly, but the query timeout provided was too
* aggressive and lower than the query's expected processing time.
* 2. Fauna was not available to service the request before the timeout was
* reached.
*
* In either case, consider increasing the `query_timeout_ms` configuration for
* your client.
*/
case 'time_out':
console.error('Time out:', error.message);
break;
/**
* An error due to a contended transaction.
*/
case 'contended_transaction':
console.error('Contended transaction:', error.message);
break;
}
// Log the status code for reference.
console.error('Status code:', statusCode);
// You can also log a summary if available.
if (error.summary) {
console.error('Error summary:', error.summary);
}
}
Is this article helpful?
Tell Fauna how the article can be improved:
Visit Fauna's forums
or email docs@fauna.com
Thank you for your feedback!