Errors

Errors are returned as RFC 7807 application/problem+json documents. The response Content-Type is application/problem+json and the body always includes at least type, title, and status.

Problem shape

{
  "type": "about:blank",
  "title": "Invalid query parameters",
  "status": 400,
  "detail": "limit: Expected number, received string"
}

Validation errors

When a request fails validation, the problem includes an errors array — one entry per offending field:

{
  "type": "about:blank",
  "title": "Invalid query parameters",
  "status": 400,
  "detail": "limit: Expected number, received string; country: Too many items",
  "errors": [
    { "field": "limit", "message": "Expected number, received string" },
    { "field": "country", "message": "Too many items" }
  ]
}

Each entry has a field (the offending field path) and a message (what was wrong with it).

Full-text search errors

These apply to the full-text q of Search jobs and Count jobs only — the q of GET /locations/search is a plain typeahead prefix (max 100 characters, no query syntax and no complexity budget) and never produces these errors.

A q that the search engine rejects returns 400 with the title Invalid search query and a detail explaining what was wrong. There is no errors array on these — the whole query is the offending value.

{
  "type": "about:blank",
  "title": "Invalid search query",
  "status": 400,
  "detail": "search query too complex: 45 terms/operators (max 40)"
}

The complexity budget counts only what you wrote, on the parsed query and before server-side synonym expansion: a bare word costs 1 node plus 1 for each OR/AND joining it (~20 OR'd words), a quoted two-word phrase costs 3 plus 1 for its OR (~10 phrases), a quoted three-word phrase costs 5 plus 1 (~6), and a -term exclusion costs 3. English stopwords are free, including inside a phrase — "director of engineering" costs 3 nodes (it parses as a two-word phrase), not 5. Synonym expansion is never charged to you, and when an expansion would grow too large the search silently runs without it rather than failing. See Search jobs for the full q contract.

Breaking change. This detail text changed: complexity rejections previously read search query too complex (numnode > 40) and counted the query after synonym expansion, which made the cost invisible and rejected ordinary multi-phrase queries. If you match on detail strings, match on the search query too complex prefix rather than the whole sentence.

A well-formed q that is simply too broad to finish in the server's time budget returns 422 instead — the query is valid, so narrow it (prefer the default q_scope=title, or add filters) rather than retrying it unchanged.

URL resolution errors

Resolve a job by URL answers a miss with 404 and the title Not Found. Two stable detail sentences separate the one case worth giving up on from the one worth retrying — match on the prefix:

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "No job matched the provided URL."
}

No job matched the provided URL. is deliberately one answer: an employer we do not index and a posting we have not seen on an employer we do index are byte-identical here, and no field distinguishes them. Coverage grows over time, so a URL that misses today can resolve tomorrow.

A missing url, a non-http(s) URL, or one longer than 2048 characters is a 400 validation problem, not a 404.

When the URL resolver itself is unreachable or too slow to answer, the lookup returns 503 with the title Service Unavailable — nothing is wrong with your request, so retry the same URL after a short pause. This is the only endpoint that returns 503 under normal operation.

Status codes