Skip to content
English
  • There are no suggestions because the search field is empty.

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, saveAndReturnEnabled and registerYourInterest.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 language parameter, en-GB or cy. The careers page settings list the languages your organisation offers in availableLanguages.

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

StatusCodeMeaning
400VALIDATION_ERRORFailed validation, or an unknown field was sent. See validationErrors. An employment or education end date before its start date also returns this on submit
400MISSING_REQUIRED_FIELDA required form field was empty. The message names it
400GAP_EXPLANATIONS_REQUIREDThe 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
400JOB_CLOSEDThe vacancy no longer takes applications
400GDPR_CONSENT_REQUIREDgdprConsent was not true
400INVALID_CANDIDATE_SOURCEsource is not one of the values in sources
400INVALID_REFERRAL_LINK, REFERRAL_EXPIREDThe referral link is for a different vacancy, or has expired
400SESSION_TOKEN_REQUIREDFile answers were sent without sessionToken
400INVALID_DOCUMENT_REFERENCEA documentId does not belong to this session and field. Upload it again
400INVALID_FIELDfieldId on an upload is unknown or is not a file field
400INVALID_FILE_TYPE, INVALID_FILE_SIZEThe file type is not accepted, its contents do not match, or it is too large
400FILE_REQUIREDThe upload had no file part
400INVALID_INPUTMalformed input, for example gapExplanations that is not valid JSON
401UPLOAD_SESSION_EXPIRED, UNAUTHORIZEDThe upload token has expired, is invalid, or is for a different vacancy
404NOT_FOUNDCompany, vacancy or group careers page not found
404CAREERS_PAGE_NOT_FOUNDThe slug could not be matched during an upload
404DOCUMENT_NOT_AVAILABLEThe attachment is not available
409DUPLICATE_APPLICATIONThis email has already applied for this vacancy
409ALREADY_EXISTSThis email has already registered its interest
409CANDIDATE_UNAVAILABLEThe candidate record could not be created. Safe to retry
413INVALID_FILE_SIZEUpload rejected for being too large before it was checked
429RATE_LIMIT_EXCEEDEDToo many requests. Wait and try again
500UPLOAD_FAILEDFile storage failed. Safe to retry
500INTERNAL_ERRORUnexpected 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.

CallLimit
Submit application20 per minute and 60 per 15 minutes
Save draft20 per minute
Upload a file30 per minute and 60 per five minutes
Renew an upload session, and the register interest form30 per minute
Register interest5 per minute
Job alerts sign-up5 per minute
Download an attachment5 per minute
Everything else100 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 fieldKey where fieldId is 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 description on the page without cleaning it.
  • Leaving the allowed origins request until the week of go live.