Help

Common API error scenarios

If you're using the Replicon API and you encounter an error, the first thing you should do is check the details.displayText and type descriptions in the error response to understand what went wrong. Refer to Understanding API error responses for more information on this.

This topic gives examples of some error scenarios that you might encounter when using the Replicon API, to help you identify and correct errors.

All examples on this page use the /ImportService2.svc/CreateUserOrApplyModifications service, unless otherwise stated.

 

Common errors

A parameter is missing or incorrect:

You have insufficient access to make the update:

The response showed Success, but the change was not made in the application:

The date you’ve included is in the wrong format

You experienced a timeout error

 

A parameter is missing or incorrect

Excluding required parameters, or including incorrect parameter names or values, are common sources of error when using the API.

Case 1: You provided two identifiers for a user

If you include multiple identifiers for a target user, you'll receive an error, even if both IDs are valid.

Example: When editing a user's settings, you accidentally provide both their login name and their URI, resulting in a '400' error. You may sometimes see '500' errors in this scenario.

Call:

{
  "target": {
    "uri": "urn:replicon-tenant:000562c10a2d4f09b34b80dac8cf9f40:user:7",
    "loginName": "[email protected]"
     },
   "modifications": {
     "firstName": {
       "value": "Beula"
     }
   },
  "userModificationOptionUri": "urn:replicon:user-modification-option:save",
  "unitOfWorkId": "54321"
}

Response:

Error '500'

{
  "error": {
    "code": "Sender",
    "correlationId": "345b23acef33489eac41d81ec6a4ab31",
    "reason": "The creator of this fault did not specify a Reason.",
    "details": {
    "displayText": "invalid target fields specified",
    "target": {
    "employeeId": null,
    "loginName": "[email protected]",
    "parameterCorrelationId": null,
    "uri": "urn:replicon-tenant:000562c10a2d4f09b34b80dac8cf9f40:user:7"
    }
  },
  "type": "InvalidUserTargetParameterError1"
  }
}

Case 2: A required parameter is missing

Certain parameters are required in all calls for a service; if you exclude a required parameter, an error will occur.

Example: You exclude the unitOfWorkId parameter when using the CreateUserOrApplyModifications service, resulting in a '400' error.

Call:

{
  "modifications": {
    "firstName": {
      "value": "Veruca"
    },
    "lastName": {
      "value": "Salt"
    },
    "emailAddress": {
      "value": "[email protected]"
    },
  }
}

Response:

Error '400'

{
  "error": {
    "code": "Sender",
    "correlationId": "e46235b42b704a60a325154ee931990e",
    "reason": "The creator of this fault did not specify a Reason.",
    "details": {
    "displayText": "Unit Of Work Id must be a non-empty string value"
    },
  "type": "MissingRequiredParameterError1"
  }
}

 

Case 3: A required sub-parameter is missing

Certain parameter values are required only if you include the parameter in your call. If you exclude a value for a required parameter you've included, an error will occur.

Example: When using the ObjectExtensionDefinitionListService service, you include the "sort" parameter, but fail to include a value for its required "isAscending" sub-parameter, resulting in a '400' error. If you omitted 'sort', the call would be successful.

Call:

{
  "page": "1",
  "pagesize": "100",
  "columnUris": [
    "urn:replicon:object-extension-tag-definition-list-column:object-extension-tag-definition"
  ],
  "sort": [
    {
      "columnUri": "urn:replicon:object-extension-tag-definition-list-column:code",
      "isAscending": null
    }
  ],
  "filterExpression": {
    "leftExpression": null,
    "operatorUri": "urn:replicon:filter-operator:text-search",
    "rightExpression": null,
    "value": null,
    "filterDefinitionUri": "urn:replicon:object-extension-tag-definition-list-filter:text"
  }
}

Response:

Error '400'

{
  "error": {
    "code": "InternalServiceFault",
    "correlationId": "57852b392e2d4989877a712876673a17",
    "reason": "The server was unable to process the request due to an internal error."
  }
}

 

Case 4: A parameter is incorrect

If you include a typo or otherwise misspell a parameter name, or include a parameter value that doesn't exist, an error will occur.

Example: You attempt to assign a supervisor, j.crew, who has not been added to your system yet, resulting in a '400' error.

Call:

{
  "target": {
    "loginName": "a.chu"
    },
  "modifications": {
    "supervisorSchedule": [
    {
      "dateRange": {
        "startDate": {
          "year": "2024",
          "month": "8",
          "day": "12"
          }
        },
      "item": {
        "loginName": "j.crew"
        }
      }
    ]
  },
  "unitOfWorkId": "24"
}

Response:

Error '400'

{
  "error": {
    "code": "Sender",
    "correlationId": "7ab6c229c3ee45b68c250e6f28b3b9e3",
    "reason": "The creator of this fault did not specify a Reason.",
    "details": {
      "notifications": [
        {
          "displayText": "Error in SupervisorSchedule - User not found",
          "failureUri": null,
          "severityUri": "urn:replicon:severity:warning"
        }
      ]
    },
    "type": "ValidationError1"
  }
}

Case 5: The user identifier is missing or incorrect

If a user name, or other parameter, does not exist or is spelled incorrectly, you'll see a Target object not found error.

Example: The login name 'randerson' doesn't exist in your tenant, so when you include that in the target, an error occurs.

Call:

{
  "target": {
    "loginName": "randerson"
  },
  "modifications": {
    "workWeekStartDay": {
      "value": {
        "uri": "urn:replicon:day-of-week:thursday"
      }
    }
  },
 "unitOfWorkId": "146585"
}

Response:

Error '400'

{
  "error": {
    "code": "Sender",
    "correlationId": "4d9e3f0d8f3f40b7b2033c9fb5aabf2a",
    "reason": "The creator of this fault did not specify a Reason.",
    "details": {
      "displayText": "Target object not found.",
      "target": {
        "employeeId": null,
        "loginName": "randerson",
        "parameterCorrelationId": null,
        "uri": null
      }
    },
    "type": "UserTargetNotFoundError1"
  }
}

Case 6: You provided the URI in the name field, or vice versa

If you include mismatched identifiers -- say, if you've changed the ID method you're using, but forgot to update the field name -- an error will occur.

Example: You accidentally include the user's URI in the login name field, resulting in a '400' error.

Call:

{
  "target": {
    "loginName": "urn:replicon-tenant:e5845cb1b0e24c0c8e0995bdef0d761c:user:5"
  },
  "modifications": {
    "firstName": {
      "value": "Angelika"
    }
  },
  "unitOfWorkId": "125645"
}

Response:

Error '400'

{
  "error": {
    "code": "Sender",
    "correlationId": "e6c0b707204c456e927f76dc057dcec8",
    "reason": "The creator of this fault did not specify a Reason.",
    "details": {
      "displayText": "Target object not found.",
      "target": {
        "employeeId": null,
        "loginName": "urn:replicon-tenant:e5845cb1b0e24c0c8e0995bdef0d761c:user:5",
        "parameterCorrelationId": null,
        "uri": null
      }
    },
    "type": "UserTargetNotFoundError1"
  }
}

You don't have sufficient access to make the update

When using Replicon's services, your actions are limited by your assigned permissions, group access, and product assignments, exactly as they would be if you were using the UI to make updates. If you attempt to make an update using an account without the required permissions, an error will occur.

Refer to Setting up a Replicon account for use with the API for more information on setting up account licenses and permissions.

 

Case 1: You don't have the permissions required to make an update

When using Replicon's services, your actions are limited by your assigned permissions, exactly as they would be if you were using the UI to make updates. Refer to How permissions work for more information.

Example: Using the UpdateTimeZoneForUser service, you attempt to update a user’s time zone. But, you don't have Users > Edit permission, under Permissions for User Profile Data in your assigned Administrator permission set, which causes an error.

Call:

{
 "userUri": "urn:replicon-tenant:e5845cb1b0e24c0c8e0995bdef0d761c:user:3",
 "timeZoneUri": "urn:replicon:time-zone:america-godthab"
}

Response:

Error '400'

{
  "error": {
    "code": "Sender",
    "correlationId": "3ab093a31435479694a2ea855ca7ea1c",
    "reason": "All access checks failed to authorize operation 'UpdateTimeZoneForUser' : The following permissions are required: Action(urn:replicon:user-action:edit-user)",
    "details": {
    "displayText": "All access checks failed to authorize operation 'UpdateTimeZoneForUser' : The following permissions are required: Action(urn:replicon:user-action:edit-user)"
  },
  "type": "AuthorizationError1"
  }
}

Case 2: You don't have access to a group the user is a member of

Your access to members belonging to particular groups can be limited within your user profile, on the Roles & Permissions tab. If you try to access a member of a group you don't have access to, an error will occur. Refer to Limiting which groups a user can access for more information.

Example: Using the UpdateTimeZoneForUser service, you attempt to update the time zone of a user who belongs to the Implementation department. But, you don't have access to users in this department, which causes an error.

Call:

{
 "userUri": "urn:replicon-tenant:e5845cb1b0e24c0c8e0995bdef0d761c:user:5",
 "timeZoneUri": "urn:replicon:time-zone:america-godthab"
}

Response:

Error '400'

{
  "error": {
    "code": "Sender",
    "correlationId": "5dd24a4c7122436587d9b04d15512a0a",
    "reason": "All access checks failed to authorize operation 'UpdateTimeZoneForUser' : The following permissions are required: Action(urn:replicon:user-action:edit-user)",
    "details": {
    "displayText": "All access checks failed to authorize operation 'UpdateTimeZoneForUser' : The following permissions are required: Action(urn:replicon:user-action:edit-user)"
  },
  "type": "AuthorizationError1"
  }
}

 

Case 3: You aren't assigned the product required to update a feature

Beyond permissions and group limits, the products you are assigned also limit what data you can view and modify in Replicon. Refer to Choosing your products to get an idea of what features are available in each product.

Example: Using the UpdateLanguageForUser service, you’re trying to change language settings for a user, but you don’t have Replicon’s Multilingual Support product assigned. This results in a '400' error.

Call:

{
 "userUri": "urn:replicon-tenant:e5845cb1b0e24c0c8e0995bdef0d761c:user:3",
 "languageUri": "urn:replicon:language:ja-JP"
}

Response:
Error '400'

{
  "error": {
    "code": "Sender",
    "correlationId": "b13c4d9eaad0456da5b551632b635129",
    "reason": "All access checks failed to authorize operation 'UpdateLanguageForUser' : The following permissions are required: Action(urn:replicon:user-action:edit-language)",
    "details": {
    "displayText": "All access checks failed to authorize operation 'UpdateLanguageForUser' : The following permissions are required: Action(urn:replicon:user-action:edit-language)"
  },
  "type": "AuthorizationError1"
  }
}

The response showed Success, but the change was not made in the application

There are a couple of scenarios where the API will show a Success response, even if a change requested in the call was not actually made in the Replicon app.

Case 1: You didn't update UnitofWorkId

When using this parameter to track iterations of your work, you must use a unique string for each new call. The API will always return the same result the ID was originally associated with. So, if you don't update the ID, each new call will return the same result.

So, if your previous call was successful, and you don’t update the ID, the next call will show Success along with the response for the previous call, even if the change in the new call was not made.

Example: If you just successfully updated settings for jane.doe, then attempt to update settings for john.deer without changing the unitOfWorkId value, your call will show Success for the second call, but john.deer's settings will not be updated in the app.

Call:

{
  "target": null,
  "template": null,
  "modifications": {
    "firstName": {
      "value": "john"
    },
    "lastName": {
      "value": "deer"
    },
    "loginName": {
      "value": "j.deer"
    }
  },
  "unitOfWorkId": 13579
}

Response:

Success ‘200’

{
  "d": {
    "errors": [
      {
        "notifications": []
      }
    ],
    "user": {
      "displayText": "doe, jane",
      "loginName": "j.doe",
      "slug": "jdoe",
      "uri": "urn:replicon-tenant:e5845cb1b0e24c0c8e0995bdef0d761c:user:902"
    }
  }
}

Case 2: A required sub-parameter is missing

For certain parameters, you may receive a Success '200' response, even though the change was not made, if you included certain parameters, but excluded their values.

Example: When using the CreateUserOrApplyModifications service, you include the time off type's policySchedule parameter, but fail to include values for it, resulting in a '400' error. Look for an 'errors' clause in the response to identify these errors.

Call:

{
  "target": {
    "uri": "urn:replicon-tenant:e5845cb1b0e24c0c8e0995bdef0d761c:user:604"
  },
  "modifications": {
    "timeOffTypes": [
      {
        "modificationOptionUri": "urn:replicon:collection-modification-option:add",
        "items": [
          {
            "timeOffType": {
              "name": "Personal Leave"
            },
            "isTimeOffAllowedAgainstThisTimeOffType": "true",
            "applyDefaultTimeOffTypePolicy": "true",
            "defaultTimeOffTypePolicyEffectiveDate": {
              "year": 2024,
              "month": 8,
              "day": 7
            },
            "policySchedule": [
              {
                "dateRange": null,
                "item": null
              }
            ]
          }
        ]
      }
    ]
  },
  "unitOfWorkId": "4444"
}

Response:

Success '200'

{
  "d": {
    "errors": [
      {
        "notifications": [
          {
            "displayText": "Error in TimeOffTypes: Add operation - Invalid date range parameter for timeOffType policySchedule",
            "failureUri": null,
            "severityUri": "urn:replicon:validation-severity:error"
          }
        ]
      }
    ],
    "user": {
      "displayText": "Bob, Punchy",
      "loginName": "punchy.bob",
      "slug": "punchybob",
      "uri": "urn:replicon-tenant:e5845cb1b0e24c0c8e0995bdef0d761c:user:604"
    }
  }
}

The date you’ve included is in the wrong format

Date fields need to use this format:

"effectiveDate": {

"year": 2024,

"month": 5,

"day": 31

Using the wrong format will typically result in an internal '500' error.

Example:

Call:

{
  "target": {
    "uri": "urn:replicon-tenant:e5845cb1b0e24c0c8e0995bdef0d761c:user:25"
  },
  "modifications": {
    "timesheetPeriodSchedule": [
      {
      "dateRange": {
        "startDate": {
        "year": 2024,
        "month": May,
        "day": 30
        }
      },
      "item": {
        "name": "Semimonthly"
        }
      }
    ]
  },
 "unitOfWorkId": "16665655"
}

Response:

Error '500'

{
 "error": {
 "code": "InternalServiceFault",
 "correlationId": "2e41d5598d4a48d982b6d3865bcea955",
 "reason": "The server was unable to process the request due to an internal error."
 }
}

You experienced a timeout error

Timeouts happen if a service takes more than 30 seconds to respond to a call. If a timeout occurs, you’ll see the Error '500' status code with details about the timeout in the response. And you’ll see an error message like this one: Operation execution timed out after exceeding timeout of 30 seconds.

Refer to Avoiding API timeouts for information on how to handle this type of error.

Start a free Replicon trial today based on your business needs

Start Free Trial

Sign Up For Our Newsletter

help-cta

Sign up for our newsletter today.