Handling Errors

A request can fail for many reasons, such as a value Hevo cannot accept, a Pipeline that does not exist, or an action that cannot run while another one is in progress. Every failure except an authentication failure returns the same response body, so your application can read these errors in the same way. Read Authentication Failures for the body returned when your credentials are missing or not valid. A request that does not match any endpoint is the other exception. Such a request has one of the following:

• A path that does not exist.
• A method that the endpoint does not accept.
• A body that is not valid JSON.

Hevo’s error handling mechanism returns these errors, and the response has a different set of fields.

A failed request returns the following fields:

For example, a request for a Pipeline that does not exist returns the following:

{
  "code": "RESOURCE_NOT_FOUND",
  "message": "No Pipeline was found with the ID 99999999.",
  "error_reference_id": null,
  "api_doc_url": "https://edge-api-docs.hevodata.com/reference/get_api-v2-pipelines-pipeline-id"
}

Refer to the following sections to handle a failed request:

• Error Codes: The values returned in the code field.
• Common Errors and How to Resolve Them: The failures that can occur, and their resolution steps.
• Retrying a Failed Request: Understand which requests you can send again.
• Authentication Failures: Handle a rejected credential, which returns a different set of fields.
• Getting Help: Contact Hevo Support about a failure you cannot correct.

Error Codes

The code field in an error response returns one of the following values:

Common Errors and How to Resolve Them

The following failures can occur when you use the API. Each one describes what causes the failure, the message Hevo returns, and the action to take.

The request is not valid

INVALID_INPUT covers anything incorrect in what you sent, such as a value outside the accepted range, a field the connector does not allow you to set, or a required field that is missing. The message names the value that was rejected and what is accepted in its place:

The limit value 9999 is not valid. Specify a value between 1 and 500.

Correct the request and send it again. Sending the same request again will not help. Values in the request body that come from a fixed list, such as load_mode or sync_type, are case-sensitive, so send them in upper case. Query parameter filters, such as state and status, are not case-sensitive. A field that an endpoint does not define is ignored, and no error is returned. The same applies to a field sent in the wrong part of the request body, so check the field names and where they belong, such as options.create_disabled rather than create_disabled on its own.

The action is not allowed from this state

An action that cannot be performed in the Pipeline's current state returns INVALID_INPUT, and the message names that state:

The Pipeline cannot be disabled because its state is Disabled. You can disable a Pipeline only from the Initialized state.

Send a request to the Get Details of a Pipeline endpoint, check its state, and bring the Pipeline to a state that allows the action before you send the request again. Read Understanding Pipeline States for more information. If the Pipeline is moving from one state to another, such as Enabling, the request returns RESOURCE_CONFLICT instead, so wait for the state to change before you send it again.

Something is already in progress

RESOURCE_CONFLICT means the request was valid but another operation is already in progress:

A job is in progress. To sync now you need to cancel the current job.

For this type of error, you can send the request again without any change. Wait for the operation to finish, and then send the same request. This error also returns the following messages:

Pipeline edits are in progress. Sync Now cannot be triggered at this time, please try again after sometime.

The request cannot be processed because the Pipeline is moving from one state to another. Wait for it to finish and try again.

The Pipeline cannot be updated because an edit is already in progress. Wait for the edit to finish and then try again.

A resync job is already in progress for one or more of these objects. Wait for the job to complete before triggering a new one. You can check the status of the resync job by sending a GET request to the /api/v2/pipelines/<pipeline_id>/jobs endpoint.

A confirmation is required

RESOURCE_CONFLICT is also returned when the request is blocked by something you must confirm before Hevo proceeds. Waiting does not clear this type of error. You send the request again with the confirmation:

• Deleting a Destination that Pipelines load into. The message names those Pipelines. Send the request again with confirm_override set to true to delete the Destination along with them. It is a query parameter, so the request is DELETE /api/v2/destinations/{destination_id}?confirm_override=true. The message is:

  3 Pipeline(s) load data into this Destination: 12 (Sales to Snowflake), 15 (Orders to Snowflake), 18 (Web events). Deleting the Destination also deletes these Pipelines and the Sources used to create them. To proceed with deletion, send the API request again with confirm_override set to true.

  The message names up to 10 Pipelines. If more load data into the Destination, it names 10 and adds the number that remain, along with a GET /api/v2/pipelines?destination_id=<destination_id> call that lists them all.

A credential was rejected

A credential that the Source rejects during the connection test returns INVALID_INPUT, with the message that your Source returns. For example:

Access denied for user 'hevo'@'10.0.0.1' (using password: YES)

Nothing is saved when this happens, so the Pipeline or Source is left as it was. Check the credentials and send the request again. If the request carried auth, Hevo also deletes the access token that it generated from those credentials. If the OAuth provider rejects your credentials, the request returns a 400. If the provider throttles the request, it returns a 429, and if the provider is unavailable, it returns a 500.

An object cannot be selected on its own

Selecting an object that a group does not allow to be selected on its own returns INVALID_INPUT. Some Sources group their objects into a parent object and its child objects. Depending on the group, a child object either always takes the selection of its parent object, or can be selected only while its parent object is selected. The message names the parent object to select. Read Managing Objects in Pipelines for more information. An object that always takes the selection of its parent object cannot be given a different selection, and the message is:

The selection of object '<child>' cannot be changed because it is a child object of '<parent>'. Select '<parent>' to automatically include all its child objects for replication, or deselect it to exclude them.

You can still name such an object, with the same selection as its parent, to change its load mode or its fields. An object that needs its parent selected can be selected once the parent is selected, in the same request or earlier, and the message is:

Object '<child>' cannot be selected for replication in the Pipeline because its parent object '<parent>' is not selected. Select '<parent>' in the same API request.

The name is already in use

Pipeline, Source, and Destination names are unique within a workspace. Two Pipelines that load data into the same Destination cannot use the same Destination prefix. Choose a different and unique name. A name or a prefix that is already in use returns INVALID_INPUT. For example, the message for a Destination name is:

A Destination named 'Sales Warehouse' already exists. Use a different name.

Retrying a Failed Request

Some failures resolve on their own, and others require you to correct the request before you send it again. The error code tells you which action to take. The following table lists the action for each error code:

Read API Response Codes for more information about the codes the API returns.

Authentication Failures

A request with missing or invalid credentials is rejected before Hevo processes it, so its body differs from every other error:

{ "error_message": "HTTP 401 Unauthorized", "api_code": 401 }

This response does not contain code, message, or error_reference_id, so handle it separately from other errors. Read Authenticating your Requests for more information.

Getting Help

Some failures cannot be corrected from your side, such as a request that Hevo could not complete. For these, the response includes an error_reference_id value that Hevo Support uses to find your request.

Contact Hevo Support and quote this identifier, along with the endpoint you called and the time of the request.