API reference · Reference

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.

2 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. The shape of an error
  2. Public jobs API
  3. Account API
  4. Handle errors in code
  5. Frequently asked questions

#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.

Public jobs API
JSON
{ "error": { "code": "invalid_parameter", "message": "limit must be a whole number from 1 to 50." } }
Account API
JSON
{ "error": "insufficient_scope", "message": "This needs the \"jobs:write\" permission, which the person did not give." }

#Public jobs API

StatuscodeWhen
400invalid_parameterA parameter has a value we cannot use: a bad limit, an unknown category, a date that is not a date
400unknown_parameterA parameter name that does not exist (also q: free-text search is not in v1)
400invalid_cursorA cursor that was changed, cut, or used with other filters than its page
401missing_key, invalid_key, revoked_keyNo key, a wrong key, or a revoked key
403insufficient_scopeThe key lacks the permission the endpoint needs
404not_foundNo such job or endpoint, or a job this API may not serve
405method_not_allowedNot a GET: the API is read-only
410goneThe job existed and has closed
429rate_limited, daily_cap_reachedOver the minute limit or the daily cap. See Rate limits
500server_errorOur fault. Try again
503api_disabled, api_unavailableThe API is switched off, or could not check your key just now

#Account API

StatuserrorWhen
401unauthorized, invalid_tokenNo key, or a wrong, expired or removed key
403insufficient_scopeThe key lacks the permission the call needs
403blocked_by_companyThe company's rule does not include your role. See Company rules
403job_writes_offThe company owner has not switched on job changes
403key_onlyJob changes need a personal key, not a connected app
403no_company, mfa_required, company_suspendedNo active company; two-factor sign-in is required; the company is suspended
403forbidden, admin_holdYour role may not change that job; GreenHired has paused the job
404job_not_found, not_foundNo such job in your company; no such endpoint
405method_not_allowedWrong method. The Allow header lists the right ones
400invalid_request, invalid_field, invalid_jobA bad body or parameter. invalid_job names the field
409profile_missing, limit_reachedThe profile is not set up yet; 500 saved jobs already
413, 415too_large, unsupported_media_typeThe body is too large; it is not application/json
429rate_limited, daily_cap_reached, company_job_capSee Rate limits. Retry-After says when to retry
500, 503server_error, temporarily_unavailableOur 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);
}

#Frequently asked questions

What is the difference between 404 and 410?
A 404 means there is no such job, or it is one the API may not serve. A 410 gone means the job existed and has closed. Remove it from your pages on a 410.
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.