API extensively uses informing through HTTP response codes. The application must process them correctly.
When an error occurs, the response body, besides the response code, will have an additional information that helps the developer to learn the cause of the error.
All errors are displayed in the format:
{
"errors": [
{
"type": "...",
"value": "..."
}
]
}Several errors can be returned at the same time. The type key is present in
each errors array object and contains a text identifier of the error class.
The value key is optional and provides more detail on the error.
Apart from the
errorsdescribed above, API can optionally return other keys left for backward compatibility. It is not recommended to use them.
If the requested resource can't be found, the
404 Not Found response will be returned and the errors array will have
the object:
{
"type": "not_found"
}If there is an error in request parameters (e.g.
GET https://api.hh.ru/vacancies/?employer_id=foo) the
400 Bad Request response will be returned, and the error array will have
the object:
{
"type": "bad_argument",
"value": "employer_id"
}If the service can't process the request at the moment, but understood it
correctly, the 503 Service Unavailable response will be returned and type
will contain service_unavailable.
In case of unforeseen situation, API will return 500.
In rare cases errors with 5** codes can be returned with the body that doesn't contain the valid json. In such a case the application should rely only on the response code.
More detail on the User-Agent title.
| HTTP code | type | value | description |
|---|---|---|---|
| 400 | bad_user_agent | unset | User-Agent title is not transferred |
| 400 | bad_user_agent | blacklisted | User-Agent value in the black list |
More detail on authorization.
Description of the fields:
| Name | Type | Value |
|---|---|---|
| error | string | One of the values described in RFC 6749. For example, invalid_request if any of the required parameters were not transferred |
| error_description | string | Additional description of the error |
Below are some of the possible errors with descriptions.
| HTTP code | error | error_description | описание |
|---|---|---|---|
| 400 | invalid_request | account not found | This error can occur if an invalid client_id and client_secret pair was transferred |
| account is locked | User account is locked. The user must contact the website support team | ||
| password invalidated | User account password is outdated. The user must restore the password on the website https://hh.ru | ||
| login not verified | User account is not verified. The user must contact the website support team | ||
| bad redirect url | Invalid redirect_url was transferred | ||
| token is empty | refresh_token was not transferred | ||
| token not found | Invalid refresh_token was transferred | ||
| code not found | The transferred authorization_code was not found | ||
| 400 | invalid_client | client_id or client_secret not found | The error can occur if this client_id was not found or has been deleted, or if an invalid client_secret was transferred |
| 400 | invalid_grant | token has already been refreshed | The error occurs when trying to re-use the refresh token |
| token not expired | The error occurs when trying to update a valid access token. access token can be updated only after expiration | ||
| token was revoked | The token was revoked. For example, a token is revoked if the password has expired | ||
| bad token | An invalid token value was transferred | ||
| code has already been used | authorization_code has already been used (it can only be used once) | ||
| code expired | authorization_code expired | ||
| code was revoke | authorization_code was revoked (if the password has expired) | ||
| token deactivated | The token was deactivated. The token is deactivated if the user has changed the password | ||
| 400 | unsupported_grant_type | unsupported grant_type | The error occurs if an invalid value in the grant_type field was transferred |
| 403 | forbidden | app token refresh too early | The error occurs if the application token is requested more than once every five minutes |
In case you make an authorized request in
api and your authorization is not valid for any reason, an error with type
oauth, and, possibly, with one of the listed values, will be returned.
| HTTP code | type | value | description |
|---|---|---|---|
| 403 | oauth | bad_authorization | authorization token doesn't exist or is not valid |
| 403 | oauth | token_expired | access_token validity period has expired, it is necessary to refresh the access_token authorization.md#refresh_token |
| 403 | oauth | token_revoked | the token is revoked by the user, the application should request a new authorization |
| 403 | oauth | application_not_found | your application has been deleted |
In case you request a paid method without buying access, the following error will be generated:
| HTTP code | type | value | description |
|---|---|---|---|
| 403 | api_access_payment | action_must_be_payed | You have requested a paid method without buying access |
If the service can return more detailed information on the error, it will be given in the response body. In this case the response code will likely be 400, 403, 409, 429, but other codes are also possible.
At the least, the application should process HTTP response statuses correctly. To facilitate the work with the application, it is recommended to also process the response type that has come. The tables listed below contain an incomplete error list; it can be extended.
When uploading artifacts, errors are possible, including:
| HTTP code | type | value | description |
|---|---|---|---|
| 400 | bad_argument | file | file not specified, or several files specified |
| 400 | bad_argument | type | incorrect parameter type value |
| 400 | bad_argument | description | description too long |
| 400 | artifacts | limit_exceeded | number of artifacts exceeded |
| 400 | artifacts | image_too_large | file size exceeds the limit |
| 400 | artifacts | unknown_format | unknown file format |
| 403 | forbidden | — | insufficient access rights |
In addition to general errors, the following errors may be returned:
| HTTP code | type | value | description |
|---|---|---|---|
| 403 | negotiations | invalid_vacancy | the vacancy from the response/invitation was archived or hidden |
| 400 / 403 | negotiations | resume_not_found | the CV from the response/invitation was hidden or deleted, or not found |
| 400 / 403 | negotiations | limit_exceeded | the limit on the responses/invitations number was exceeded |
| 403 | negotiations | wrong_state | the action on the response/invitation in this status is impossible |
| 403 | negotiations | empty_message | the empty message text was sent |
| 403 | negotiations | too_long_message | the too long message text was sent |
| 403 | negotiations | address_not_found | the address sent for the action does not exist or belongs to another employer |
| 403 | negotiations | not_enough_purchased_services | the required paid services are not available, this usually refers to access to the resume database |
| 403 | negotiations | not_enough_purchased_services | the paid services are insufficient, usually CV database service |
| 403 | negotiations | in_a_row_limit | the number of successive messages is exceeded; the opponent must reply to the message in order the employer is able to send new messages |
| 403 | negotiations | overall_limit | messages limit exceeded |
| 403 | negotiations | no_invitation | negotiations are unavailable as there was no invitation in the response |
| 403 | negotiations | message_cannot_be_empty | negotiation message cannot be empty |
| 403 | negotiations | disabled_by_employer | negotiation by response is disabled by the employer |
| 403 | negotiations | resume_deleted | the message can't be sent as the CV referenced in the response is deleted or hidden |
| 403 | negotiations | archived | the message can't be sent as the vacancy referenced in the response is archived |
When adding to the list of selected vacancies the following errors can be returned, in addition to the error code:
| HTTP code | type | value | description |
|---|---|---|---|
| 403 | vacancies_favorited | vacancy_archived | the vacancy is archived and cannot be added to the list of selected number of selected vacancies exceeds the limit |
| 403 | vacancies_favorited | limit_exceeded | authorization_code has already been used (it can only be used once) |
In addition to an error code, the following errors may be returned when posting and editing a vacancy:
| HTTP code | type | value | description |
|---|---|---|---|
| 400 | vacancies | field_name | the is an error in a job's field, where the field_name is the key of the upper level field and the reason field may be missing |
| 403 | vacancies | not_enough_purchased_services | the purchased services are not enough to publish or update this type of job |
| 403 | vacancies | quota_exceeded | the manager's quota for the publication of this type of job is exhausted |
| 403 | vacancies | duplicate | a similar job has already been published; this error can be disabled by force (when adding or editing) |
| 403 | vacancies | creation_forbidden | jobs cannot be published by the current manager |
| 403 | vacancies | unavailable_for_archived | you cannot edit an archived job |
| 403 | vacancies | conflict_changes | a conflict was detected between changes to the job's data (read more) |
| 403 | vacancies | can_not_accept_kids | you can't publish jobs to search for applicants with a minimum age of 14 (read more) |
| reason | description |
|---|---|
| is_empty | empty value |
| wrong_size | wrong value size |
| is_too_short | value size is too small |
| is_too_long | value size is too big |
| currency_code_is_invalid | the salary currency is incorrect |
| chosen_area_is_not_a_leaf_or_not_exist | the vacancy location is incorrect or is not the final region (city, town) |
| email_in_description | the vacancy description contains an email |
| anonymous_vacancy_contains_address | an anonymous vacancy should not contain the employer's address |
| anonymous_vacancy_has_real_company_name | the vacancy title should not contain the employer's company name |
| only_for_anonymous_type | this action is only available for anonymous vacancies |
| address_is_disabled | address is unavailable |
| vacancy_type_employer_billing_type_mismatch | the vacancy type is incompatible with current billing type |
| only_for_direct_type | this action is only available for direct vacancies |
| address_is_empty_with_checked_show_metro_flag | empty address was entered together with an indication to show the metro station |
| address_has_no_metro_but_checked_show_metro_flag | a metro station is not available at the entered address, but the option to show the metro station is selected |
| default_vacancy_branded_template_is_invalid_or_not_enough_purchased_services | branded vacancy template is entered incorrectly, or you have not paid for the service allowing you to use a branded vacancy template |
| department_code_prohibited_in_anonymous_vacancy | you cannot specify a department code for an anonymous vacancy |
| branded_template_prohibited_in_anonymous_vacancy | you cannot use a branded template for an anonymous vacancy |
In addition to the error code, the following errors can be returned when extending a job:
| HTTP code | type | value | description |
|---|---|---|---|
| 403 | vacancies | not_enough_purchased_services | the purchased services are insufficient for prolongation of this type of vacancy |
| 403 | vacancies | quota_exceeded | the manager's quota for posting of this type of vacancies has been exceeded |
| 403 | vacancies | prolongation_forbidden | extension of vacancies is unavailable for the current manager |
| 403 | vacancies | unavailable_for_archived | extension of vacancies is unavailable for the archived vacancy |
| 403 | vacancies | too_early | premature extension |
In addition to general errors, the following errors can be returned when adding and editing an employer's manager:
| HTTP code | type | value | reason | description |
|---|---|---|---|---|
| 400 | managers | field_name | error in the field_name field | |
| 403 | managers | already_exist | a manager with this email address already exists | |
| 403 | managers | creation_limit_exceeded | the limit for creating managers has been reached | |
| 403 | managers | field_name | not_editable | the field_name field cannot be edited |
In addition to general errors, the following errors can be returned when getting or updating a resume:
| HTTP code | type | value | description |
|---|---|---|---|
| 400 | resumes | total_limit_exceeded | the allowed number of resumes is exceeded (this applies only to applicants) |
| 429 | resumes | view_limit_exceeded | the allowed number of resume views is exceeded (this applies only to employers) |
Adding hidden jobs to the list
In addition to general errors, the following errors can be returned when adding hidden jobs to the list:
| HTTP code | type | value | description |
|---|---|---|---|
| 400 | vacancies_blacklist | limit_exceeded | the allowed number of hidden jobs is exceeded |
| 404 | vacancies_blacklist | not_found | the job to be added to the list has not been not found |
Adding hidden companies to the list
In addition to general errors, the following errors can be returned when adding company's hidden jobs to the list:
| HTTP code | type | value | description |
|---|---|---|---|
| 400 | employers_blacklist | limit_exceeded | the allowed number of hidden jobs is exceeded |
| 404 | employers_blacklist | not_found | the job to be added to the list has not been not found |
| HTTP code | type | value | description |
|---|---|---|---|
| 400 | bad_argument | per_page | an invalid number of items per page was passed (the maximum value is 100) |
| HTTP code | type | value | description |
|---|---|---|---|
| 400 | resume_visibility_list | unknown_employer | an unknown employer ID was passed |
| 400 | resume_visibility_list | limit_exceeded | visibility list limit exceeded |
| 400 | resume_visibility_list | too_many_employers | too many employers were passed |
| HTTP code | type | value | описание |
|---|---|---|---|
| 400 | bad_argument | id | an invalid employer ID was passed |
| 400 | resume_visibility_list | too_many_employers | too many employers were passed |
| HTTP code | type | value | reason | описание |
|---|---|---|---|---|
| 400 | bad_argument | id | too_many_bulk_items | too many IDs |
| 400 | bad_argument | id | an invalid ID was passed |
| HTTP code | type | value | description |
|---|---|---|---|
| 403 | manager_extra_accounts | manager_extra_account_not_found | Incorrect Account ID in the header |
| 403 | manager_accounts | used_manager_account_forbidden | Work Account is blocked |
If User Account is blocked, the following error message will be generated:
{
"errors": [
{
"type": "manager_accounts",
"value": "used_manager_account_forbidden",
"allowed_accounts": [
{
"id": "1",
"employer": {
"id": "12345678",
"name": "Alpha Corp."
}
},
{
"id": "2",
"employer": {
"id": "87654321",
"name": "Beta Inc."
}
}
]
}
]
}where allowed_accounts contains an array of the accounts available for this token
Array elements are similar to the result in the list of the Work Accounts