Errors and status codes
Every GreenHired API error has a stable code you can program against. See the error shapes of both APIs and what each status and code means.
On this page
#The shape of an error
Program against the code, not the message: messages can change, codes will not. The two APIs word the body slightly differently.
{ "error": { "code": "invalid_parameter", "message": "limit must be a whole number from 1 to 50." } } { "error": "insufficient_scope", "message": "This needs the \"jobs:write\" permission, which the person did not give." } #Public jobs API
| Status | code | When |
|---|---|---|
| 400 | invalid_parameter | A parameter has a value we cannot use: a bad limit, an unknown category, a date that is not a date |
| 400 | unknown_parameter | A parameter name that does not exist (also q: free-text search is not in v1) |
| 400 | invalid_cursor | A cursor that was changed, cut, or used with other filters than its page |
| 401 | missing_key, invalid_key, revoked_key | No key, a wrong key, or a revoked key |
| 403 | insufficient_scope | The key lacks the permission the endpoint needs |
| 404 | not_found | No such job or endpoint, or a job this API may not serve |
| 405 | method_not_allowed | Not a GET: the API is read-only |
| 410 | gone | The job existed and has closed |
| 429 | rate_limited, daily_cap_reached | Over the minute limit or the daily cap. See Rate limits |
| 500 | server_error | Our fault. Try again |
| 503 | api_disabled, api_unavailable | The API is switched off, or could not check your key just now |
#Account API
| Status | error | When |
|---|---|---|
| 401 | unauthorized, invalid_token | No key, or a wrong, expired or removed key |
| 403 | insufficient_scope | The key lacks the permission the call needs |
| 403 | blocked_by_company | The company's rule does not include your role. See Company rules |
| 403 | job_writes_off | The company owner has not switched on job changes |
| 403 | key_only | Job changes need a personal key, not a connected app |
| 403 | no_company, mfa_required, company_suspended | No active company; two-factor sign-in is required; the company is suspended |
| 403 | forbidden, admin_hold | Your role may not change that job; GreenHired has paused the job |
| 404 | job_not_found, not_found | No such job in your company; no such endpoint |
| 405 | method_not_allowed | Wrong method. The Allow header lists the right ones |
| 400 | invalid_request, invalid_field, invalid_job | A bad body or parameter. invalid_job names the field |
| 409 | profile_missing, limit_reached | The profile is not set up yet; 500 saved jobs already |
| 413, 415 | too_large, unsupported_media_type | The body is too large; it is not application/json |
| 429 | rate_limited, daily_cap_reached, company_job_cap | See Rate limits. Retry-After says when to retry |
| 500, 503 | server_error, temporarily_unavailable | Our fault; personal keys are switched off for now |
#Handle errors in code
const res = await fetch(url, { headers: { Authorization: 'Bearer ' + key } });
if (!res.ok) {
const body = await res.json().catch(() => ({}));
// Public API: body.error.code. Account API: body.error (a string).
const code = typeof body.error === 'object' ? body.error?.code : body.error;
if (res.status === 401) throw new Error('Key rejected: make or request a new one');
if (res.status === 429) throw new Error('Rate limited, retry after ' + res.headers.get('retry-after') + 's');
throw new Error('GreenHired API error ' + res.status + ' ' + code);
} res = requests.get(url, headers={"Authorization": "Bearer " + key}, timeout=15)
if not res.ok:
try:
body = res.json()
except ValueError:
body = {}
err = body.get("error")
code = err.get("code") if isinstance(err, dict) else err # public API vs account API
raise RuntimeError("GreenHired API error %s %s" % (res.status_code, code)) #Frequently asked questions
- What is the difference between 404 and 410?
- A
404means there is no such job, or it is one the API may not serve. A410 gonemeans the job existed and has closed. Remove it from your pages on a410. - Should I retry a 500?
- Yes, a few times with a short wait. If it keeps failing, write to support@greenhired.com with the time and the request you made, but never your key.
- Why do I get 415 unsupported_media_type?
- You sent a body that is not labelled
Content-Type: application/json, or in another format such as a form. Send the body as JSON with that header. Calls with no body need no header.
Was this page helpful?