Common API Error Responses
This article briefly describes common API errors you may encounter when working with the Lucernex RESTful API. This article is not all-inclusive, so if you encounter an error that is not listed here, consult with your Lucernex Project Consultant.
200 OK
200 OK errors occur when the call was successful, but some information sought does not exist.
Cause: Object sought by non‐existent LxID
Description: This error happened because the call referenced an LxID value that does not exist in the client's Lucernex environment.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: PUT
URL: {{url}}/rest/businessObject
Raw XML Input:
<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
<Employer lxID="999888">
<EmployerName>Acme Employer</EmployerName>
</Employer>
</LxERP>XML Response:
<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
<error fatal="true" lookup="false" lxID="999888" objectType="Employer">
<message><div class='frmError'>Error processing entry, Employer lookup failed</div></message>
<position>3</position>
</error>
</results>Cause: Malformed field name
Description: This error is caused when there is a typo in a tag. In the below example, you can see that the <City> tag was misspelled as <Cit>.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: PUT
URL: {{url}}/rest/businessObject
Raw XML Input:
<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
<Employer clientID="TestEmployer1">
<EmployerName>Acme Employer</EmployerName>
<Cit>Boston</Cit>
</Employer>
</LxERP>XML Response:
<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
<error fatal="false" lookup="false" clientID="TestEmployer1" objectType="Employer">
<message>Ignoring tag 'Cit'='Boston'</message>
<position>3</position>
</error>
<success create="false" delete="false" update="true" clientID="TestEmployer1" lxID="859578" objectType="Employer"/>
</results>400 Bad Request
400 Bad Request errors occur when there are issues with the way you built your API call. You will need to modify your API call in order to successfully process the request.
Cause: Incorrect Field Name in FIQL criteria
Description: This error occurs because the field name in the FIQL criteria is not valid for the database table. In the below example, the CheckNumber does not belong to the Contract database table, it belongs to the PaymentTransaction database table.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: GET
URL: {{url}}/rest/businessObject/Contract/details?fiql=CheckNumber==0012345&fields=ContractName
Text Response: fiql criteria field CheckNumber is not a valid field of objectType Contract
Cause: Incorrect field name in field list
Description: This error occurs because the field name in the field list is not valid for the database table. In the below example, the Abbrev does not belong to the Employer database table. It's possible that this field is a firm-defined field that belongs to another database table.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: GET
URL: {{url}}/rest/businessObject/Employer/details?fiql=EmployerName==Acme%20Co&fields=Abbrev
Text Response: Abbrev is not a valid field of objectType Employer
Cause: Non‐existent operator
Description: This error occurs because Lucernex only supports the AND FIQL operator, not OR.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: GET
URL: {{url}}/rest/businessObject/Contract/details?fiql=ContractName==12345,ContractName==54321&fields=ContractName
Text Response: Only AND criteria (;) is currently supported amongst values, failed to process criteria type OR
Cause: Wrong field delimiter
Description: This error occurs when semicolons are used in field parameters rather than commas.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: GET
URL: {{url}}/rest/businessObject/Contract/details?fiql=ContractName==12345&fields=ContractName;ExpireDate
Text Response: ContractName;ExpireDate is not a valid field of objectType Contract
Cause: Non‐existent table name in XML input
Description: This error occurs when there is a typo in the database table tag. In the below example, the proper database table name would be "Employer", but "Employ" was entered instead.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: POST
URL: {{url}}/rest/businessObject
Raw XML Input:
<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
<Employ clientID="EMP_12345‐SITE">
<EmployerName>16 Fifth Avenue</EmployerName>
</Employ>
</LxERP>Text Response: Required argument 'bo' is null
Cause: Attempt to create a new object with an already existing ClientID
Description: This error occurs because the user tried to create a new record with a ClientID that had already been assigned to another record. The ClientID field must be unique.
If you are trying to update a record using a POST command, you should include the allowUpdate="true" parameter in your API call.
This error message can be useful if you are actually trying to create new records, because it informs you if a ClientID is already in use.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: POST
URL: {{url}}/rest/businessObject
Raw XML Input:
<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
<Employer clientID="Existing ClientID">
<EmployerName>Acme Employer</EmployerName>
</Employer>
</LxERP>XML Response:
<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
<error fatal="false" lookup="false">
<message>Creating objectType: Employer, message: Record already exists with [lxID: 859578, clientID: Existing ClientID]</message>
</error>
</results>401 Unauthorized
401 Unauthorized errors typically occur either when you do not specify an authentication token, or your authentication token is invalid.
Cause: Bad URL
Description: This error occurred because the URL is case-sensitive. The 'O' in businessObject needs to be capitalized for the call to process correctly.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: Any
URL: {{url}}/rest/businessobject
HTML Response:
<!DOCTYPE HTML PUBLIC "‐//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML>
…
<p><b><font face="Verdana" size="2">~~Unable to access the requested page, you do not have access to the requested functionality. #~</font></b></p>
</td></tr></table>
</div>
</body>
</HTML>404 Not Found
404 errors occur when the URL you are using is incorrect in some way.
Cause: Incomplete URL
Description: This error occurs when the URL is not complete. In the below example, it is likely that the user wanted to access {{url}}/rest/businessObject .
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: Any
URL: {{url}}/rest/bus
JSON Response:
{
"code": 404,
"type": "unknown"
}Cause: Non‐existent table name
Description: This error occurs when there is a typo in the database table name in the URL. In the below example, the proper database table name would be "Employer", but "Employ" was entered instead.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: GET
URL: {{url}}/rest/businessObject/Employ
Text Response: Unknown objectType: Employ
Cause: Object sought by non‐existent LxID
Description: This error occurs when the LxID that is requested does not exist. The most common cause of this error is when a user deleted the record.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Example 1
Method: GET
URL: {{url}}/rest/businessObject/Employer/12345
Text Response: Unable to find objectType: Employer, id: 12345
Example 2
Method: DELETE
URL: {{url}}/rest/businessObject/Employer/12345
XML Response:
<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
<error fatal="true" lookup="true">
<message>Unable to find objectType: Employer, id: 12345</message>
</error>
</results>Cause: Object sought by non‐existent ClientID
Description: This error occurs when the ClientID that is requested does not exist. The most common cause of this error is when a user deleted the record.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Example 1
Method: GET
URL: {{url}}/rest/businessObject/Employer/clientid/EMP‐12345
Text Response: Unable to find objectType: Employer, clientID: EMP‐12345
Example 2
Method: DELETE
URL: {{url}}/rest/businessObject/Employer/clientid/EMP‐12345
XML Response:
<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
<error fatal="true" lookup="true">
<message>Unable to find objectType: Employer, clientID: EMP‐12345</message>
</error>
</results>405 Method Not Allowed
405 Method Not Allowed errors typically occur when you are not allowed to use the selected method for the database table. For example, some database tables only allow updates to certain fields—such as the SLPeriod and SLSummary tables, which are used for accounting schedules—or they do not allow DELETE calls.
Cause: Incomplete URL
Description: The error below occurred because the record that the user wanted to update is not specified in the URL.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: GET, DELETE
URL: {{url}}/rest/businessObject
JSON Response:
{
"code": 405,
"type": "unknown“
}Cause: Bad table name
Description: The error below occurred because the object name is misspelled.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: DELETE
URL: {{url}}/rest/businessObject/Employ
JSON Response:
{
"code": 405,
"type": "unknown“
}Cause: Incorrect URL
Description: The error below occurred because the ClientID is incorrect.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: POST, PUT
URL: {{url}}/rest/businessObject/Employer/clientid/EMP‐12345
JSON Response:
{
"code": 405,
"type": "unknown“
}408 Request Timeout
408 Request Timeout errors occur when excessive (concurrent) load is detected for REST api usage within the current firm in Lucernex.
Cause: Too many requests sent to IWMS concurrently
Description: This error is returned if excessive (concurrent) load is detected for REST api usage within the current firm in Lucernex. Requests are queued and processed as load subsides, that is, as current in-process calls are completed. Once a max queue time is reached for a request, the error message is returned.
Retry: Retry should be attempted after an appropriate pause, (for example, 20 seconds) to let the system recover from current load conditions. If higher levels of possible concurrency are desired (more configured threads for various independent jobs) use a larger pause interval. This way, if the Lucernex server begins to experience load timeouts, it will not be overwhelmed with requests from the (larger) number of job threads that will be waiting for Lucernex api resources.
Method: GET, POST, PUT, DELETE
URL: {{url}}/rest/businessObject
Text Response: Query url [/rest/businessObject/RunReport/details], params [{fiql=ReportID==RecordCount2}] timed out after waiting 10 seconds for an execution permit.
415 Unsupported Media Type
415 Unsupported Media Type errors occur when you try to use input types that are incompatible with the Lucernex RESTful API.
Cause: Input in a format other than XML or JSON
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: POST, PUT
URL: {{url}}/rest/businessObject
Raw Input: This input is no good.
JSON Response:
{
"code": 408,
"type": "unknown“
}500 Internal Server Error
500 Internal Server errors are server-side errors where the server is incapable of completing the request.
Cause: Missing required input
Description: This error occurred because the user didn't provide any input for the POST or PUT request.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: POST, PUT
URL: {{url}}/rest/businessObject
Raw XML: [blank]
JSON Response:
{
"code": 500,
"type": "unknown“
"message": "com. ctc. wstx. exc. WstxEOFException: Unexpected EOF in prolog\n at [row,col {unknown‐source}]: [1,0]"
}Cause: Non‐existent table name in XML input
Description: This error occurred because the database table name is misspelled.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: PUT
URL: {{url}}/rest/businessObject
Raw XML Input:
<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
<Employ clientID="EMP_12345‐SITE">
<EmployerName>Acme Employer</EmployerName>
</Employ>
</LxERP>XML Response:
<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
<error fatal="true" lookup="false">
<message>Required argument 'bo' is null!</message>
</error>
</results>Cause: Missing close tag for element in XML input
Description: This error occurred because the XML is not properly formatted. The user would need to add a closing tag for the <Employer> tag.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: POST, PUT
URL: {{url}}/rest/businessObject
Raw XML Input:
<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
<Employer clientID="EMP_12345‐SITE">
<EmployerName>Acme Employer</EmployerName>
</LxERP>JSON Response:
{
"code": 500,
"type": "unknown",
"message": "com. ctc. wstx. exc. WstxParsingException: Unexpected close tag </LxERP>; expected </Employer>. \n at [row,col {unknown‐source}]: [5,7]"
}Cause: Object sought by non‐existent ClientID
Description: This error occurred because the ClientID specified by the user does not exist in the system. The server is telling the user that it cannot complete an update without a valid ClientID.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: PUT
URL: {{url}}/rest/businessObject
Raw XML Input:
<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
<Employer clientID="Non‐Existent Employer">
<EmployerName>Acme Employer</EmployerName>
</Employer>
</LxERP>XML Response:
<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
<error fatal="true" lookup="false">
<message>Error updating objectType: Employer, id: null, message: Required argument 'lxID' is null!</message>
</error>
</results>Cause: Object sought without LxID or ClientID
Description: This error occurred because the user did not include an LxID or ClientID in their PUT request. Since PUT is an update, the system requires that you include one of these two identifiers.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: PUT
URL: {{url}}/rest/businessObject
Raw XML Input:
<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
<Employer>
<EmployerName>Acme Employer</EmployerName>
<City>Boston</City>
</Employer>
</LxERP>XML Response:
<?xml version="1.0" encoding="UTF‐8" standalone="yes"?>
<results>
<error fatal="true" lookup="false">
<message>Error updating objectType: Employer, id: null, message: Required argument 'lxID' is null!</message>
</error>
</results>Cause: Reserved character in XML input
Description: This error occurred because there were reserved characters included in the XML.
Retry: Retry should not be attempted; the redundant call will generate additional load.
Method: POST, PUT
URL: {{url}}/rest/businessObject
Raw XML Input:
<?xml version="1.0" encoding="UTF‐8"?>
<LxERP>
<Employer clientID="TestEmployer1">
<EmployerName>Acme Employer</EmployerName>
<City>Boston&</City>
</Employer>
</LxERP>JSON Response:
{
"code": 500,
"type": "unknown",
"message": "com. ctc. wstx. exc. WstxUnexpectedCharException: Unexpected character '<' (code 60) (expected a name start character)\n at [row,col {unknown‐source}]: [5,17]"
}502 Bad Gateway
502 Bad Gateway errors occur when when API calls exceed the limits set at the load balancer or other network devices..
Cause: Calls exceed limits set at the load balancer
Description: This error can be returned for long running api calls that exceed limits set at the load balancer (may also be returned by other intermediary network devices) or when the server fulfilling the request becomes unavailable.
The default timeout for Lucernex UI servers (e.g. uat.lucernex.com) is 5 minutes. If an http response is not generated within that time the load balancer will timeout the http connection and return 502. Currently api-uat-lucernex.com is configured for a 30 minute connection timeout.
Retry: Retry can be attempted after an appropriate pause, (for example, 20 seconds) to let the system recover from current load conditions.
Method: GET, POST, PUT, DELETE
URL: {{url}}/rest/businessObject
JSON Response:
{
"code": 502,
"type": "unknown“
}