Error Handling

Transfers and Connection Tests

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": {
        "error_code": "PRQL-PVER",
        "title": "BigQuery Authentication Failed",
        "blame": "third_party",
        "documentation_url": "https://docs.prequel.co/docs/error-codes",
        "message": "The BigQuery connection was refused. Please check that 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 Blame

We 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 status

There 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

{
    "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/docs/error-codes",
            "message": "The BigQuery connection was refused. Please check that 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

{
    "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

{
    "status": "success",
    "data": {
        "transfer": {
            ...
            "model_metrics": [
                {
                    ...
                    "error": {
                        "error_code": "PRQL-PVER",
                        "title": "BigQuery Authentication Failed",
                        "blame": "third_party",
                        "documentation_url": "https://docs.prequel.co/docs/error-codes",
                        "message": "The BigQuery connection was refused. Please check that 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
                    }
                }
            ]
        }
    }
}