Docs

Search the docs

Guides, sections and API endpoints

Get started

Errors

The one shape every error has, the types to branch on, and how to handle each.

The API answers with standard HTTP status codes: 2xx for success, 4xx for something in the request, and 5xx for something on our side.

The error shape

Every error has the same body: a list of what went wrong, usually one.

JSON
{
  "detail": [
    {
      "type": "conflict",
      "loc": ["body", "email"],
      "msg": "A candidate with email '[email protected]' already exists."
    }
  ]
}
Field
typeA stable, machine-readable code. Branch on this.
locWhere the problem is: ["body", "email"] for a field of the body, ["query", "limit"] for a query parameter, ["path", "job_id"] for part of the URL, or just ["body"] when it's the request as a whole.
msgWhat went wrong, in a sentence for people. It may be reworded, so don't match on it.

Validation errors (422) also have input, what was sent, and sometimes ctx, with details like the limit that was exceeded.

Status codes and types

StatusTypeMeans
400validation_errorA value can't be used, though it's well formed, like a resume that isn't a PDF.
401api_key_requiredNo API key was sent.
401invalid_api_keyThe key is wrong, expired or revoked.
403insufficient_scopeThe key isn't allowed this; see scopes.
404resource_not_foundIt doesn't exist, or belongs to another organization.
409conflictIt clashes with what's there, like a second candidate with the same email.
422missing, uuid_parsing, string_too_long, less_than_equal, timezone_aware, value_error, …A parameter or field doesn't validate. One entry per problem.
429Too many requests. Wait and retry.
500Something broke on our side. Retry later, and tell us if it lasts.
503Briefly unavailable. Wait and retry.

A 422 lists every problem with the request at once:

JSON
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "last_name"],
      "msg": "Field required",
      "input": { "first_name": "Ana" }
    },
    {
      "type": "less_than_equal",
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 100",
      "input": "500",
      "ctx": { "le": 100 }
    }
  ]
}

Handling errors

Retry 429, 500 and 503 with a backoff; fix the request for the rest. A 409 is often information rather than failure: the candidate or application you were making is already there.

import time
import httpx

class HireHappyError(Exception):
    def __init__(self, response: httpx.Response):
        self.status = response.status_code
        self.errors = response.json().get("detail", []) if response.content else []
        self.type = self.errors[0]["type"] if self.errors else None
        super().__init__(f"{self.status} {self.type}: {self.errors}")

def request(client: httpx.Client, method: str, path: str, **kwargs):
    for attempt in range(5):
        response = client.request(method, path, **kwargs)
        if response.status_code in (429, 500, 502, 503, 504):
            time.sleep(float(response.headers.get("Retry-After", 2**attempt)))
            continue
        if response.is_error:
            raise HireHappyError(response)
        return response.json() if response.content else None
    raise HireHappyError(response)