# 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 'ana.ribeiro@example.com' 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](https://hirehappy.io/docs/authentication#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:

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


```python
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)
```

```js
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, []);
}
```

