HTTP API reference
This following pages contain reference documentation for Fauna’s HTTP APIs.
Fauna exposes two sets of HTTP APIs to interact with its services:
API | Purpose | Base URL |
---|---|---|
Run FQL queries and consume event sources for a Fauna database. |
|
|
Manage features of a Fauna account. |
|
Query API endpoint conventions
This section covers API conventions for the Query API endpoint.
Failed queries
A query can fail because of one of these classes of errors:
Error classification | Error cause |
---|---|
Check error |
Before execution, one or more query validation checks failed. |
Runtime error |
An error occurred during query execution. This might include multiple errors and isn’t associated with a particular method. |
Abort error |
An |
Query status
The HTTP status code indicates the request completion status. You should try to first handle the error based on the Fauna error code. If the query returns an error code that isn’t included in the list, handle the error as appropriate for the HTTP status code.
The Query API reference shows the status codes returned by each method.
HTTP status codes are grouped as follows:
Range | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
200-299 |
Successful query
|
||||||||||||
400-499 |
Client error
|
||||||||||||
500-599 |
Server error
|
General status code reference: RFC9110 9110 HTTP Semantics
Error handling example
The following example shows how to handle errors based on the 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 fucntion contains a detailed description of each of
Fauna's error codes and how to handle them.
*/
function handleFaunaError(error, statusCode) {
switch (error.code) {
/**
* An error due to 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 deleted document.
*/
case 'document_deleted':
console.error('Document deleted:', error.message);
break;
/**
* An error due to document not found.
*/
case 'document_not_found':
console.error('Document not found:', error.message);
break;
/**
* A type of AuthorizationError that indicates the user does not have permission to perform the operation.
*/
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 invalid argument.
*/
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 null value.
*/
case 'null_value':
console.error('Null value:', error.message);
break;
/**
* Stack overflow error
*/
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;
/**
* Throttling Error indicates some capacity 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('Unbound variable:', 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);
}
}
Wire protocol: Encode FQL as JSON
The Query endpoint uses the wire protocol to encode FQL-typed as JSON.
See Wire protocol: Encode FQL as JSON |
---|
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!