> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notealy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error envelope and common status codes.

All non-2xx responses follow the same shape:

```json theme={null}
{
  "statusCode": 400,
  "message": "phone must be 10–15 digits, optional leading +",
  "error": "Bad Request"
}
```

`message` may be an array when multiple validation errors are returned at once:

```json theme={null}
{
  "statusCode": 400,
  "message": [
    "name is required and must not be empty",
    "phone must be 10–15 digits, optional leading +"
  ],
  "error": "Bad Request"
}
```

## Common status codes

| Status                  | Meaning                                                                                 | Recovery                                        |
| ----------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `400 Bad Request`       | Validation failed                                                                       | Fix the payload and retry                       |
| `401 Unauthorized`      | Token missing, invalid, revoked or expired                                              | Issue a new token                               |
| `403 Forbidden`         | Token is valid but lacks the scope this endpoint requires                               | Re-issue the token with the right scopes        |
| `404 Not Found`         | Resource id does not exist in your organization                                         | Confirm the id and the org the token belongs to |
| `409 Conflict`          | Uniqueness conflict (e.g. duplicate domain) — rare; most write endpoints upsert instead | Read the resource first                         |
| `429 Too Many Requests` | Rate limit hit                                                                          | Wait until `X-RateLimit-Reset`, then retry      |
| `5xx`                   | Notealy server error                                                                    | Retry with exponential backoff                  |

## Idempotency

Several write endpoints are idempotent by design:

* `POST /v1/people` upserts on phone → email → `externalId`.
* `POST /v1/companies` upserts on `domain`.
* `POST /v1/people/:id/tags` only emits `contact.tag_added` for newly attached tags.

Safe-to-retry responses make it easy to build at-least-once delivery from your side without duplicates on ours.