Skip to main content

Error Handling

When your Connector interacts with SyncHive, there are potential points of failure. Generally, issues can arise when sending requests to SyncHive or receiving requests from SyncHive. The following sections will provide a detailed overview of these potential errors.

Requests to SyncHive​

There are several scenarios where errors might occur when making requests to SyncHive. For HTTP requests, a JSON payload will accompany an HTTP error.

JSON Example
{
  "type": "http://www.meaningful.co.nz/limber-sync/retry-later",
  "typeCode": "RETRY_LATER",
  "status": 500,
  "title": "Retry later",
  "detail": "Retry later",
  "uuid": "3721a351-9285-4375-99db-f1fe1d8277b7",
  "message": "Oops, something went wrong"
}

Retries​

Messages with a type of http://www.meaningful.co.nz/limber-sync/retry-later should be treated as retryable, and the request to SyncHive should be retried.

Aside from that, HTTP requests with the following status codes should also be treated as retryable:

  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

Requests from SyncHive​

For requests from SyncHive to a Connector, the expectations are outlined below.

Outbound Publish​

When SyncHive publishes data to a Connector, the following API is called:

PUThttps://{my_connector_url}/v1/data

On an error, SyncHive expects a nicely formatted message.

  1. An HTTP status code of 500
  2. A property type with a value of http://www.synchive.com/common/publish-error.
  3. A property logCode should be populated with an appropriate event code.
  4. A property detail should be populated with a end user friendly message.
    1. If the error contains technical information that may help an end-user, those should go to the technicalInfo property
  5. If the failure is retryable, the property retryable populated with true.
  6. If the request was able to partially succeed and has an external ID to store, the linkIdentities property populated to link external IDs back into SyncHive. See: Linking External IDs.
Example Response
{
  "type": "http://www.synchive.com/common/publish-error",
  "detail": "Could not connect to ShopifyNZ.

    The HTTP API Key Value you provided is incorrect.

    Please provide a valid HTTP API Key Value to the ShopifyNZ Integration and try again.",
  "logCode": "4005E",
  "retryable": false,
  "linkIdentities": {
    "integrationKey": "shopify_nz_integration",
    "linkIdentities": [
      {
        "iri": "https://schema.limbergraph.com/limber/Product#00006e95-ed86-46b6-a36e-b7e339bfb0b2",
        "externalId": "632910392"
      }
    ]
  }
}

Process Message​

When the platform calls a Connector to handle a process message, the following request is called:

PUThttps://{my_connector_url}/v1/process

On an error, SyncHive expects a nicely formatted message.

  1. An HTTP status code of 500
  2. A property type with a value of http://www.synchive.com/common/process-error.
  3. A property logCode should be populated with an appropriate event code.
  4. A property detail should be populated with a end user friendly message.
    1. If the error contains technical information that may help an end-user, those should go to the technicalInfo property
  5. If the failure is retryable, the property retryable populated with true.
Example Response
{
  "type": "http://www.synchive.com/common/process-error",
  "detail": "Could not connect to ShopifyNZ.

    The HTTP API Key Value you provided is incorrect.

    Please provide a valid HTTP API Key Value to the ShopifyNZ Integration and try again.",
  "logCode": "4003E",
  "retryable": true
}