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 innerstatus
field, within thedata
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
}
}
]
}
}
}
Updated 2 days ago