Errors

Every error uses the same envelope:

{
  "error": {
    "code": "validation_error",
    "message": "The request body contains invalid fields.",
    "details": [
      { "field": "address.countryCode", "message": "must be equal to one of the allowed values" }
    ]
  }
}

Field	Description
`code`	Machine-readable and stable. Use it in your code.
`message`	Human-readable, for developers. Wording may change; do not parse it.
`details`	Present for field-level failures. One entry per field, with `field` and `message`.

New codes may be added at any time. Treat an unknown code by its HTTP status.

Status codes

Status	Meaning
`400`	The request cannot be processed as sent: invalid JSON, cursor, version, language, or filter value.
`401`	Authentication failed.
`404`	The resource does not exist, or belongs to another company.
`422`	The request is well-formed but fails validation or a business rule.
`429`	Rate limit exceeded.
`500`	An unexpected error on JOIN's side. The message is always generic.

Error codes

Platform

Code	Status	Cause	What to do
`authentication_required`	`401`	No `Authorization: Bearer` header.	Send the token.
`token_invalid`	`401`	Token malformed, unknown, revoked, or the plan has no API access.	Check the token in Settings → Developer → API tokens.
`malformed_json`	`400`	The body is not valid JSON.	Fix the request body.
`cursor_invalid`	`400`	The cursor is invalid or expired.	Restart from the first page.
`filter_invalid`	`400`	A filter value could not be resolved. `details` names the filter.	Correct the filter.
`unsupported_api_version`	`400`	The `Join-Version` header names a version the API does not serve.	Omit the header or send a supported version.
`unsupported_language`	`400`	The `language` parameter is not one of `nl`, `en`, `fr`, `de`, `it`, `es`.	Send a supported language.
`validation_error`	`422`	One or more fields are missing, of the wrong type, or out of range. `details` lists them.	Correct the fields named in `details`.
`not_found`	`404`	The path does not exist.	Check the URL.
`rate_limit_exceeded`	`429`	The token exceeded a rate limit.	Wait for `Retry-After` seconds.
`unknown`	`500`	Unexpected server error.	Retry with backoff; contact support if it persists.

Not found

Code	Status
`application_not_found`	`404`
`candidate_not_found`	`404`
`job_not_found`	`404`
`note_not_found`	`404`
`office_not_found`	`404`

Business rules

Code	Status	Endpoint	Cause
`application_already_exists`	`422`	Create an application	The candidate already has an application on this job.
`candidate_blocked`	`422`	Create an application	The candidate is blocked by your company.
`job_archived`	`422`	Create an application	The job is archived.
`stage_not_in_pipeline`	`422`	Move an application	The stage is not part of the job's pipeline. Use a stage from `GET /v3/jobs/{jobId}/pipeline`.
`application_rejected`	`422`	Move an application	The application is rejected. Un-reject it in JOIN first.
`note_limit_reached`	`422`	Create a candidate note	The candidate already has 50 notes.
`office_default_required`	`422`	Update an office	The default office cannot be set to `isDefault: false`. Make another office the default.
`office_is_default`	`422`	Delete an office	The default office cannot be deleted.
`office_referenced_by_active_jobs`	`422`	Delete an office	Active jobs use this office.
`job_limit_reached`	`422`	Create or update a job	Publishing would exceed the company's active-job limit.
`salary_visibility_restricted`	`422`	Create or update a job	The job's country requires a public salary.
`custom_questions_not_in_plan`	`422`	Create or update a job	Custom screening questions require the Advanced or Enterprise plan.

Retrying

Status	Retry?
`429`	Yes, after `Retry-After` seconds.
`500`	Yes, with exponential backoff. A `POST` may already have succeeded: check before retrying a create.
`400`, `401`, `404`, `422`	No. The same request fails again until it is changed.