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

- Source: https://greenhired.com/developers/api/v1/errors/
- Section: GreenHired developers · API · Reference
- Last updated: 2026-11-21

## 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." }
```

> **Info:** A request body must be JSON, sent with `Content-Type: application/json`. A body in another format, or with no content type, is refused with `415 unsupported_media_type`. A call with no body (publish, close, delete) needs no header.

## 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](https://greenhired.com/developers/api/v1/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](https://greenhired.com/developers/api/v1/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](https://greenhired.com/developers/api/v1/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

*JavaScript*

```javascript
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);
}
```

*Python*

```python
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 `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](mailto: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.

## Related pages

- https://greenhired.com/developers/api/v1/limits/
- https://greenhired.com/developers/api/v1/authentication/
- https://greenhired.com/developers/api/v1/employer-jobs/
