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

Core API

Run FQL queries and consume event streams for a Fauna database.

https://db.fauna.com

Account API

Manage features of a Fauna account.

https://account.fauna.com

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 abort() call caused the transaction to abort.
Example

You can see that the response fields are the same as a successful response, except there is an error field describing the error instead of a data field, and the summary field includes more descriptive error information. This error is caused by misspelling the all() method.

{
    "error": {
        "code": "invalid_function_invocation",
        "message": "The function `al` doesn't exist on `Collection`"
    },
    "summary": "error: The function `al` doesn't exist on `Collection`\nat *query*:1:12\n  |\n1 | Collection.al()\n  |            ^^\n  |",
    "txn_ts": 1689785459623670,
    "stats": {
        "compute_ops": 1,
        "read_ops": 0,
        "write_ops": 0,
        "query_time_ms": 0,
        "contention_retries": 0,
        "storage_bytes_read": 0,
        "storage_bytes_write": 0,
        "rate_limits_hit": []
    },
    "schema_version": 0
}

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

HTTP status code Description

200

Successful operation.

400-499

Client error

HTTP status code Description

400

Failed operation, bad request.

401

Fauna can’t authenticate the request because of an invalid or missing authentication token.

409

Excessive contention on a document while executing a query.

429

Query exceeded a capacity limit.

440

Client timeout exceeded, but the timeout is set lower than the expected query processing time. Distinguished from a 503 status because this is considered a successful response regarding service availability.

500-599

Server error

HTTP status code Description

500

Unexpected error.

502

Router couldn’t reach the backend.

503

Unexpected timeout.

504

Router timeout trying to connect to the backend.

General status code reference: RFC9110 9110 HTTP Semantics

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!