Overview

This topic discusses error cases when using the feature service's createReplica and synchronizeReplica operations. This includes errors and failures due to losing a network connection as well as errors to specific features when synchronizing edits. The rollbackOnFailure value and sync model chosen by the client affects the errors that can occur. See the RollbackOnFailure and Sync Models topic for more details.

Network connectivity

When a client issues a REST request, it receives a response with an HTTP status. It's possible for a network connection to go down before the client receives the response. If the process is synchronous (for example, the feature service synchronizeReplica operation executed with async=false), the request is lost and must be reissued. If the process is asynchronous (for example, the feature service synchronizeReplica operation executed with async=true), the client can reissue a status check request once network connectivity is restored.

HTTP status

A REST request issued to ArcGIS Server returns an HTTP status. An HTTP status of 200 means that the request has been processed. Any other HTTP status indicates that there has been a problem. For example, an HTTP status of 500 indicates an internal server error (for example, the server has gone down). Once the issue has been resolved, the client can reissue the request.

The client gets the response once it receives an HTTP status of 200. The response includes the results of the operation as returned by a service.

Synchronize Replica and Create Replica operation responses

When the synchronizeReplica and createReplica operations complete with an HTTP status of 200, clients need to check the response. If using synchronous processing, the operation is complete when a response is returned. If using asynchronous processing, the operation is complete when a status of Completed or Failed is returned. For the synchronizeReplica operation, you may additionally get a status of CompletedWithErrors when the operation completes.

In the completed response, the client needs to check for the presence of an error property. If there is an error in the response, the operation has failed. The error includes a REST error code and information on why the error occurred. For example, the following is returned if synchronizeReplica has failed due to the replica having been unregistered on the server:

{
  "error": {
    "code": 404,
    "message": "Unable to complete operation.",
    "details": [
      "Replica with this GUID does not exist on the server"
    ],
    "infos": []
  }
}

Another example is when an error occurs when importing edits that cause the operation to be rolled back. This can happen when synchronizing where the rollbackOnFailure parameter is set to true. In this case, the infos array in the response includes information on the specific failed edit, including the edit result error code.

{
  "error": {
    "code": 400,
    "message": " Operation rolled back.",
    "details": [],
    "infos": [
      {
        "errorCode": 1001,
        "description": "Field: <value> is not nullable. Cannot set null value.",
        "layerId": 7,
        "objectGUID": "{419d227b-2a61-43c4-8884-4b7b5bf3eabb}",
        "objectType": 0
      }
    ]
  }
}

If there is no error property in the completed response, clients need to check the responseType property. If the responseType is esriReplicaResponseTypeEdits, the response includes edits and edit results returned from the service. The serverGen(s) is included with the edits in the response (for example, within the delta SQLite geodatabase in the response).

{
  "transportType": "esriTransportTypeUrl",
  "responseType": "esriReplicaResponseTypeEdits",
  "replicaName": "NE_10141",
  "resultUrl": "https://relic:6443/arcgis/rest/directories/arcgisoutput/sync_test5_bamb_ora_MapServer/_ags_data{B5330F8549CF43BABD49B73F22768AA4}.geodatabase",
  "submissionTime": 1376157770000,
  "lastUpdatedTime": 1376157776000,
  "status": "Completed"
}

If there is no error property and the responseType is esriReplicaResponseTypeNoEdits, then there have been no edits on the services data since the last sync. This only applies when the syncDirection is download or bidirectional and the dataFormat is sqlite. The response includes new serverGen numbers that clients need to persist and use on the next synchronizeReplica call. The following example shows a response for a replica with a perReplica sync model:

{
  "transportType": "esriTransportTypeUrl",
  "responseType": "esriReplicaResponseTypeNoEdits",
  "replicaServerGen": 1374861421011,
  "replicaName": "ags_gfs_3889",
  "resultUrl": "",
  "submissionTime": 1374861420000,
  "lastUpdatedTime": 1374861422000,
  "status": "Completed"
}

Edit results

The synchronize replica operation will return edit results when the following occur:

• There were errors applying edits to the server during the synchronizeReplica operation. In these cases, the edit results describe the errors that occurred.
• The operation is called with returnIdsForAdds set to true. Here, the edit results include the IDs of features added to the server during the sync.

Edit results can be returned only when syncDirection is upload or bidirectional, since these sync directions involve applying edits to the server.

The edit results include the following information about each error:

Each error has an edit results error code and a description where the value of the code indicates the error. Edit results include errors when applying individual edits, errors that cause all edits on a layer to fail, or errors that fail the whole synchronizeReplica operation.

For example, an update attempted on a feature that violates the feature service's ownership-based access control rules is returned as follows:

If an insert is attempted that violates a field's nonnullable constraint, the following is returned:

When the returnIdsForAdds parameter is set to true, edit results include the objectID on the server and the globalID of any features that were inserted on the server during the sync. In this case, this is not an error, so the code and description are Null. For example:

If the synchronizeReplica operation is called with dataFormat as json, edit results are embedded in the JSON result. If the synchronizeReplica operation is called with dataFormat as SQLite, the edit results are in the GDB_DataChangesEditResults table in the delta SQLite geodatabase.

See the Feature service error codes topic for a detailed list of the edit results error codes and descriptions (see the Working with errors section below for more details). The same error codes are used for errors returned during connected editing with the feature service.

Work with errors

This section discusses cases where the operation has failed or has completed and returned edit results.