• iCIMS Corporate Site
  • iCIMS Partners
  • Additional Resources
  • Recent Updates
  • FAQ
  • Login
  • GETTING STARTED
    • Getting Started
    • Integration Approval Process
    • How-To Videos
    • Acceptable Use Policy
    • Terms of Use
    • Release Notes
  • API
    • Licenses
    • Connecting, Authenticating, and Identity
    • Authenticating API Calls with OAuth 2.0
    • HMAC
    • Error Handling
    • Error Reporting Standard for Vendors
    • Field Types
  • Standard Integrations
    • Assessments
    • Candidate Matching
    • Candidate Ranking
    • Document Management
    • Data Analytics and Reporting
    • Human Capital Management
    • I-9 & E-Verify
    • Job Advertising
    • Job Posting
    • Partner Screening
    • Reference Checks
    • Tax Credits
    • Video Interviewing
  • Prime Integrations
    • Prime Assessments
    • Prime Background Screen
      • Implementation
  • Endpoints
    • Binary Collection Fields
    • Binary Files
    • Collection Fields
    • Customers
    • Direct Linking
    • iForms
    • Job Distributor
    • Job Portal API
    • List API
    • Offer API
    • Onboard API
    • Profiles
    • Schema API
    • Search API
    • Workflows
  • Streaming Endpoints
  • Data Models
    • iForms
    • Job
    • Location
    • New Hire Category
    • Onboarding Workflow
    • Person
    • Recruiting Workflow
    • Room
    • Sourcing Workflow
    • Talent Pool
    • Event
    • Validation
  • Integration Events
    • Best Practices
    • Application Complete
    • Job Edit
    • Job Posting
    • Job Unposting
    • Onboard Portal Task
    • Status Flow Update
  • OTHER TECH
    • File-Based Transfers
      • Scheduled Import/Export Licenses
      • Imports
      • Exports
      • File Formatting
      • Import File Examples
    • SAML
    • Standard XML Feed for Job Boards
  • Forum

Search form

Developer Resources
  • Getting Started
  • API
    • Licenses
    • Connecting, Authenticating, and Identity
    • Authenticating API Calls with OAuth 2.0
    • HMAC
    • Error Handling
    • Error Reporting Standard for Vendors
    • Field Types
  • Standard Integrations
  • Prime Integrations
  • Endpoints
  • Streaming Endpoints
  • Data Models
  • Integration Events
  • OTHER TECHNOLOGY
  • FAQ

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: 

Error Code Status Code Definition
INTERNAL_ERROR 0 500 - Internal Server Error Used for errors on the Platform.
FIELD_REQUIRED 1 400 - Bad Request Used for a missing field.
RESOURCE_NOT_FOUND 2 404 - Not Found Used for trying to pull a resource that does not exist.
RESOURCE_ACCESS_DENIED 3 404 - Not Found Used for trying to access a forbidden resource. 
FIELD_INVALID 4 400 - Bad Request Used for when the information in a field is invalid.
INVALID_FORMAT 5 400 - Bad Request Used for when the translation between JSON and field representation fails. 
AUTHENTICATION_INVALID_CREDENTIALS 6 401 - Unauthorized Used if the provided username and password credentials are invalid.
AUTHENTICATION_MISSING_CREDENTIALS 7 401 - Unauthorized Username or Password has been provided for authentication.
AUTHENTICATION_LOCKED_OUT 8 401 - Unauthorized  The user name has been locked preventing any more login attempts.
AUTHENTICATION_NOT_AUTHORIZED 9 403 - Forbidden Given user does not have rights to use web services.
SSL_NOT_USED 11 403 - Forbidden The request is not using SSL.
FIELD_NOT_FOUND 12 404 - Not Found Used when a field is not accessible.
FIELD_NOT_ACCESSIBLE 13 403 - Forbidden Used when a field is not accessible.
PROFILE_NOT_ACCESSIBLE 14 400 - Bad Request Used when a profile is not accessible.
PROFILE_DUPLICATE 15 400 - Bad Request Processing of the client request would have resulted in a duplicate profile.
WORKFLOW_DUPLICATE 16 400 - Bad Request Processing of the client request would have resulted in a duplicate workflow entry.
INVALID_CONTENT_DISPOSITION 17 403 - Forbidden The Content-Disposition header lacked required meta-data from the client.
SITE_BOOTING 18 403 - Forbidden The Platform is currently booting up. 
SITE_OUTAGE 19 403 - Forbidden The Platform is experiencing an outage.
SITE_FAILED_TO_BOOT 21 403 - Forbidden The Platfrorm has failed to boot and could be down for an extended period of time. 
INVALID_SETUP 22 403 - Forbidden An entity such as a form is set up in such a way that it can not be used with web services. 
REQUEST_TIMEOUT 23 403 - Forbidden The client did not produce a request within the time that the server was prepared to wait. 
REAL_CLIENT_IP_MISSING 24 403 - Forbidden The request lacks a 'realclientip' HTTP header, which is necessary for white listing based secruity.
IP_BLOCKING_NOT_CONFIGURED 25 403 - Forbidden A IP Address based white list was not configured for the credentials being used to authenticate.
IP_DENIED_BY_BLOCKING 26 403 - Forbidden The IP address of the client used to access the REST API was not part of the IP Address white list for the provided credentials. 
RESOURCE_SIZE_LIMIT_EXCEEDED 27 413 - Request Entity Too Large The uploaded resource representation exceeded the enforced limits.
CONTENT_LENGTH_MISSING 28 400 - Bad Request The request is missing the required HTTP Content Length Header.
UN_SUPPORTED_INTERNAL_ENDPOINT 29 N/A The endpoint is for internal use only, un-documented and can change at any moment.
REQUEST_METHOD_INVALID 30 405 - Method Not Allowed The HTTP Request Method is not allowed or invalid for the URL being accessed.
RESPONSE_TYPE_INVALID 31 406 - Not Acceptable The resource identified by the request cannot provide any of the acceptable content-types specified in the Accept header of the client request.
RESPONSE_MEDIA_TYPE_UNSUPPORTED 32 415 - Unsupported Media Type The request is in a format not supported by the requested resource for the requested method.
REQUEST_INVALID 33 400 - Bad Request

The request could not be understood by the server due to mal-formed syntax. 

PARAMETERS_MISSING 34 400 - Bad Request The request cannot be processed due to missing parameter(s).
UNSAFE_DATA 35 422 - Unprocessable Entity Used for when the data provided contains potential threats.
LIST_NOT_ACCESSIBLE 36 400 - Bad Request Used when the list is not accessible.
LIST_NODE_INVALID 37 400 - Bad Request Used when a the information in a list node or its attributes is not valid.
LIST_NODE_MISSING 38 400 - Bad Request Used when a request is missing a list node.
JOB_UNPOST_SIDE_EFFECT 39 200 - OK Used when a job unpost request will have unintended side effects (ie. unposting a Career Portal post when job board post links back to it).
AUTHENTICATION_HMAC_VERIFICATION_FAILED 40 401 - Unauthorized Verification of HMAC signature failed.
SERVICE_UNAVAILABLE 41 503 - Service Unavailable Used for temporary service unavailable errors such as connection issues with the database.
 
RATE_LIMIT_THRESHOLD_50_PERCENT 50 200 - OK Used when the rate limit for the web service endpoints has reached 50% of the daily threshold.
RATE_LIMIT_THRESHOLD_75_PERCENT 51 200 - OK Used when the rate limit for the web service endpoints has reached 75% of the daily threshold.
RATE_LIMIT_THRESHOLD_90_PERCENT 52 200 - OK Used when the rate limit for the web service endpoints has reached 90% of the daily threshold. Action recommended.
RATE_LIMIT_THRESHOLD_100_PERCENT 53 200 - OK Used when the rate limit for the web service endpoints has reached 100% of the daily threshold.
RATE_LIMIT_THRESHOLD_500_PERCENT 54 200 - OK Used when the rate limit for the web service endpoints has reached 500% of the daily threshold. Action requied.

 

Do you have any questions or feedback regarding iCIMS' API documentation? Email the team
See Recent Site Updates

© 2023 iCIMS, Inc. All rights reserved.
Privacy Notice | Terms of Use