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. |