Error Handling

In the event that there is a problem processing an API request, iCIMS follows standard behaviors across all API endpoints to inform clients about request problems.

The Status Code of the HTTP response indicates the overall success or failure of a request. Any Status Code in the 2XX range indicates success.

In addition to Status Codes, information about problems encountered when processing a request are communicated through X-Warning or X-Error HTTP response headers. A response may contain multiple HTTP response headers indicating there were multiple problems while handling a particular request. In addition to the header, an error will be provided in the JSON response. 

• All problems reported in the header will follow a consistent format. The format for an X-Warning or X-Error HTTP response header is as follows: X-Warning:<Code>:<Detail> OR X-Error:<Code>:<Detail>. (E.g., X-Error:2:Job not found.)
  • Code: a unique code consisting of numbers used to reference specific errors that occur in the Platform
  • Detail: a description of the problem 
  • Note: If the warning or error is specific to a field, the field ID will also be sent as part of the response header: X-Warning:<Code>:<Field ID>:<Detail> OR X-Error:<Code>:<Field ID>:<Detail>. (E.g., X-Warning:4:StartDate: Field name must be all lowercase.)
• A message containing information about the error will also be provided in the JSON response. An example of this message is as follows:

{ 
   "errors":[ 
        { 
             "errorMessage":"Job not found.", 
             "errorCode":2
         } 
   ] 
}

Note: If the warning or error is specific to a field, the field ID will also be sent as part of the JSON response, as in the following example:

{

  "warnings": [

    {

      "errorMessage": "StartDate: Field name must be all lowercase.",

      "errorCode": 4

    }

}

Current Errors

iCIMS uses the following warnings and errors: