Public Careers API responses, errors and rate limits
How every Public Careers API response is wrapped, which error codes you can get back and the request limits that apply.
How every Public Careers API response is wrapped, which error codes you can get back and the request limits that apply.
This guide is for web developers building a custom careers page. You need your careers slug and a working request to the public careers endpoints first. See Building a custom careers page with the Public Careers API for the set-up.
Response format
Every JSON response is wrapped. Read what you need from data.
{
"success": true,
"data": { }
}
- Unknown fields are rejected. A query parameter or body field Recruit does not recognise returns
400 VALIDATION_ERROR. Build request bodies field by field and do not forward a whole form state object. - Size. A JSON request body can be up to 2 MB. Files go through a separate upload call.
- Dates. Every date is an ISO 8601 string in UTC, for example
2026-08-14T09:00:00.000Z. - Caching. Responses carry no cache headers. If you render on a server, cache the job list for a few minutes. That keeps your page quick without leaving closed vacancies on show for long.
- Features that differ by organisation. Read fields such as
jobAlertsEnabled,applyButtonEnabled,saveAndReturnEnabledandregisterYourInterest.enabled, and show or hide the matching part of your page. Do not assume they are on. - Language. The job list and filter calls accept an optional
languageparameter,en-GBorcy. The careers page settings list the languages your organisation offers inavailableLanguages.
Error format
Errors use the same wrapper with success set to false.
{
"success": false,
"error": {
"code": "MISSING_REQUIRED_FIELD",
"message": "Required field \"Right to work\" is missing",
"validationErrors": [
{ "field": "email", "message": "email must be an email", "code": "INVALID" }
]
}
}
Branch on error.code. The message wording can change. validationErrors only appears on some errors. Where a form rule fails, the entries inside it can carry the code REQUIRED (a required file is missing), MIN_ENTRIES or MAX_ENTRIES (a repeating group has too few or too many entries).
Error codes
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_ERROR | Failed validation, or an unknown field was sent. See validationErrors. An employment or education end date before its start date also returns this on submit |
| 400 | MISSING_REQUIRED_FIELD | A required form field was empty. The message names it |
| 400 | GAP_EXPLANATIONS_REQUIRED | The employment gap rule refused the submit because a gap has no explanation or reason. Fetch the application form again and keep the candidate's answers |
| 400 | JOB_CLOSED | The vacancy no longer takes applications |
| 400 | GDPR_CONSENT_REQUIRED | gdprConsent was not true |
| 400 | INVALID_CANDIDATE_SOURCE | source is not one of the values in sources |
| 400 | INVALID_REFERRAL_LINK, REFERRAL_EXPIRED | The referral link is for a different vacancy, or has expired |
| 400 | SESSION_TOKEN_REQUIRED | File answers were sent without sessionToken |
| 400 | INVALID_DOCUMENT_REFERENCE | A documentId does not belong to this session and field. Upload it again |
| 400 | INVALID_FIELD | fieldId on an upload is unknown or is not a file field |
| 400 | INVALID_FILE_TYPE, INVALID_FILE_SIZE | The file type is not accepted, its contents do not match, or it is too large |
| 400 | FILE_REQUIRED | The upload had no file part |
| 400 | INVALID_INPUT | Malformed input, for example gapExplanations that is not valid JSON |
| 401 | UPLOAD_SESSION_EXPIRED, UNAUTHORIZED | The upload token has expired, is invalid, or is for a different vacancy |
| 404 | NOT_FOUND | Company, vacancy or group careers page not found |
| 404 | CAREERS_PAGE_NOT_FOUND | The slug could not be matched during an upload |
| 404 | DOCUMENT_NOT_AVAILABLE | The attachment is not available |
| 409 | DUPLICATE_APPLICATION | This email has already applied for this vacancy |
| 409 | ALREADY_EXISTS | This email has already registered its interest |
| 409 | CANDIDATE_UNAVAILABLE | The candidate record could not be created. Safe to retry |
| 413 | INVALID_FILE_SIZE | Upload rejected for being too large before it was checked |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests. Wait and try again |
| 500 | UPLOAD_FAILED | File storage failed. Safe to retry |
| 500 | INTERNAL_ERROR | Unexpected error |
Rate limits
Limits apply to each IP address. Everything shares a general limit of 100 requests per minute, and some calls have a tighter one.
| Call | Limit |
|---|---|
| Submit application | 20 per minute and 60 per 15 minutes |
| Save draft | 20 per minute |
| Upload a file | 30 per minute and 60 per five minutes |
| Renew an upload session, and the register interest form | 30 per minute |
| Register interest | 5 per minute |
| Job alerts sign-up | 5 per minute |
| Download an attachment | 5 per minute |
| Everything else | 100 per minute |
Going over a limit returns 429 RATE_LIMIT_EXCEEDED. If you render on a server, all your visitors share one IP address as far as Recruit can tell, so cache the job list and do not fetch it for every page view. Candidates on a shared office network can also reach the application limit together, so show a clear "wait a moment" message and not a general error.
Common mistakes
- Reading from the top level of the response and not from
data. - Expecting the same paging shape from the group feed.
- Sending
fieldKeywherefieldIdis needed. - Showing every field without checking
showWhen, so candidates are blocked by questions that should be hidden. - Sending a phone number without its country code.
- Sending your own confirmation email.
- Treating a closed vacancy as an error and not as a closed page.
- Putting HTML from
descriptionon the page without cleaning it. - Leaving the allowed origins request until the week of go live.