FindNeo Developers

Errors and limits

Error responses

Every error is a JSON problem document (RFC 7807) with the content type application/problem+json:

{
  "type": "https://errors.findneo.com/not-found",
  "title": "Not found",
  "status": 404,
  "code": "ERR_NOT_FOUND",
  "detail": "Not found.",
  "instance": "/v1/website/jobs/6f1c2a9e-3b4d-4c55-9a1e-2f0b7d8e9c10",
  "traceId": "0192f3a1c4d27e8b"
}

Branch on code. title and detail are written for people and may be reworded at any time. Quote traceId when you ask for help: it finds the call in FindNeo's logs.

Error codes

Status Code When
401 ERR_UNAUTHENTICATED No X-Api-Key header, or the key is not valid or was revoked.
403 ERR_FORBIDDEN A list-only key called an application call, or a browser on a website the key doesn't allow made the call.
404 ERR_NOT_FOUND No published job with that id. Unpublished, confidential, closed and missing jobs all answer the same way.
409 ERR_DUPLICATE The candidate (recognised by email) already has an active application for this job.
413 ERR_PAYLOAD_TOO_LARGE The uploaded file is larger than 10 MB.
415 ERR_UNSUPPORTED_MEDIA_TYPE The uploaded file is not a PDF, DOC or DOCX.
422 ERR_VALIDATION_FAILED Something in the request is not valid. fields lists each problem with a JSON Pointer path into the body.
422 ERR_CONSENT_REQUIRED The application has no consent: true.
422 ERR_APPLICATION_CAP_REACHED The candidate has reached the company's limit of active applications.
429 ERR_RATE_LIMITED Too many calls. See below.
500 ERR_INTERNAL Something went wrong at FindNeo. Try again later; if it keeps happening, send us the traceId.

For 409 ERR_DUPLICATE and 422 ERR_APPLICATION_CAP_REACHED, the detail is written for the candidate and names nothing private, so you can show it to them as it is.

Rate limits

Calls Limit
listJobs, getJob, getApplicationForm 60 a minute from one IP address
uploadFile 60 an hour from one IP address, and 10 every 10 minutes from one IP address for one job
submitApplication 5 an hour from one IP address, and 20 an hour for one job

The application limits are shared with the FindNeo career page: an application from your website and one from the career page count against the same job's limit.

Over a limit, the call answers 429 ERR_RATE_LIMITED. When the response has a Retry-After header, wait that many seconds before trying again; the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers say where you stand. Don't retry in a tight loop.

Because the limits are per IP address, call the application calls from the candidate's browser. A server sending every candidate's application from one address reaches 5 an hour almost at once. For the job list, a few minutes of caching on your server keeps you well inside 60 a minute.

Retrying

Answer Retry?
429 Yes, after Retry-After.
500, 502, 503, 504, or no answer Yes, a few times, waiting longer each time.
Any other 4xx No: the same request will fail the same way. Fix it first.

Retrying submitApplication after a timeout can't create a second application: FindNeo recognises the candidate by email, and the retry answers 409 ERR_DUPLICATE if the first one arrived.