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.
{
"detail": [
{
"type": "conflict",
"loc": ["body", "email"],
"msg": "A candidate with email '[email protected]' already exists."
}
]
}| Field | |
|---|---|
type | A stable, machine-readable code. Branch on this. |
loc | Where 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. |
msg | What 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
| Status | Type | Means |
|---|---|---|
400 | validation_error | A value can't be used, though it's well formed, like a resume that isn't a PDF. |
401 | api_key_required | No API key was sent. |
401 | invalid_api_key | The key is wrong, expired or revoked. |
403 | insufficient_scope | The key isn't allowed this; see scopes. |
404 | resource_not_found | It doesn't exist, or belongs to another organization. |
409 | conflict | It clashes with what's there, like a second candidate with the same email. |
422 | missing, uuid_parsing, string_too_long, less_than_equal, timezone_aware, value_error, … | A parameter or field doesn't validate. One entry per problem. |
429 | Too many requests. Wait and retry. | |
500 | Something broke on our side. Retry later, and tell us if it lasts. | |
503 | Briefly unavailable. Wait and retry. |
A 422 lists every problem with the request at once:
{
"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)class HireHappyError extends Error {
constructor(status, errors) {
super(`${status} ${errors[0]?.type}: ${errors[0]?.msg}`);
this.status = status;
this.errors = errors;
this.type = errors[0]?.type;
}
}
async function request(method, path, body) {
for (let attempt = 0; attempt < 5; attempt++) {
const response = await fetch(`https://api.hirehappy.io/v1${path}`, {
method,
headers: {
Authorization: `Bearer ${process.env.HIREHAPPY_API_KEY}`,
...(body && { "Content-Type": "application/json" }),
},
body: body && JSON.stringify(body),
});
if ([429, 500, 502, 503, 504].includes(response.status)) {
const wait = Number(response.headers.get("Retry-After") ?? 2 ** attempt);
await new Promise((resolve) => setTimeout(resolve, wait * 1000));
continue;
}
if (!response.ok) {
const { detail = [] } = await response.json().catch(() => ({}));
throw new HireHappyError(response.status, detail);
}
return response.status === 204 ? null : response.json();
}
throw new HireHappyError(503, []);
}