Coded error handling

Transfers and connection tests

Sensitive TracesIn accordance with data policy and security guarantees, Prequel also offers Sensitive Trace Webhooks to provide unmodified errors directly to your infrastructure. Follow the link to learn how to receive full errors from your Prequel environment, or continue reading about in-application coded errors below.

When a transfer or connection test encounters an issue, an error object is returned. This object includes an error code, a message, and other fields to help identify the problem and provide steps to resolve it.

Understanding Our Terminology

First Party: You, the Prequel user.
Third Party: Your customers.

Error format in transfers and connection tests

When an error occurs during a transfer or connection test, the response will include an error object with the following format:

Error object

{
    "error": {
        "error_code": "PRQL-PVER",
        "title": "BigQuery Authentication Failed",
        "blame": "third_party",
        "documentation_url": "https://docs.prequel.co/export/error-handling/error-codes",
        "message": "The BigQuery connection was refused. Please check that the provided connection principal has been granted sufficient access.",
        "trace": "...unable to ping bigquery database via service account impersonation..." // Full trace of the error
     }
}

Blame

The blame indicates who is responsible for the error and can have one of the following values:

first_party: The error is caused by the Prequel user (you).
third_party: The error is caused by your customer.
prequel: The error is caused by Prequel.
host: The error is caused by whoever is hosting Prequel (our cloud or your deployment).
unknown: No specific blame assigned.

Unknown BlameWe cannot anticipate (nor have we encountered) every error that the third party systems may raise. Error codes and messages are frequently changing and errors that we’ve encountered before should appear with a label and message. However, errors we have not encountered before will appear without a blame, and Prequel support can help you diagnose them.

Error code, title, and message

The error_code, title, and message fields provide more specific information about the error.

error_code: A short code that uniquely identifies the error.
title: A user-facing title for the error.
message: A user-facing message that explains the error.

Refer to the Error Codes page for a full list of error codes.

Trace

The trace field contains the full trace of the error. This can be useful for debugging the error. We don’t recommend surfacing this to users.

Connection test response format

Understanding statusThere is a top level status field that indicates the status of the request itself. The inner status field, within the data object, indicates the status of the connection test. This allows you to distinguish between an error that occurs when communicating with the Prequel API and an error that occurs during the connection test.

The data object on the connection test response contains the results of the connection test, assuming the request itself was successful. It will have a status of success or error.

Example: connection test failed due to third-party user error

Connection test failure

{
    "status": "success",
    "data": {
        "status": "error",
        "success": false,
        "error": {
            "error_code": "PRQL-PVER",
            "title": "BigQuery Authentication Failed",
            "blame": "third_party",
            "documentation_url": "https://docs.prequel.co/export/error-handling/error-codes",
            "message": "The BigQuery connection was refused. Please check that the provided connection principal has been granted sufficient access.",
            "trace": "...unable to ping bigquery database via service account impersonation...", // Full trace of the error
        }
    }
}

Example: connection test succeeded

Connection test success

{
    "status": "success",
    "data": {
        "status": "success",
        "success": true,
    }
}

Transfer response format

Errors on transfers can be found in model_metrics. This is a list of objects corresponding to the models being transferred. Prequel reports errors per-model.

Example: partial transfer failure

Partial transfer failure

{
    "status": "success",
    "data": {
        "transfer": {
            ...
            "model_metrics": [
                {
                    ...
                    "error": {
                        "error_code": "PRQL-PVER",
                        "title": "BigQuery Authentication Failed",
                        "blame": "third_party",
                        "documentation_url": "https://docs.prequel.co/export/error-handling/error-codes",
                        "message": "The BigQuery connection was refused. Please check that the provided connection principal has been granted sufficient access.",
                        "trace": "...unable to ping bigquery database via service account impersonation..." // Full trace of the error
                    }
                }
            ]
        }
    }
}

​Transfers and connection tests

​Error format in transfers and connection tests

​Blame

​Error code, title, and message

​Trace

​Connection test response format

​Example: connection test failed due to third-party user error

​Example: connection test succeeded

​Transfer response format

​Example: partial transfer failure

Transfers and connection tests

Error format in transfers and connection tests

Blame

Error code, title, and message

Trace

Connection test response format

Example: connection test failed due to third-party user error

Example: connection test succeeded

Transfer response format

Example: partial transfer failure