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

# Errors

> Understand error responses and HTTP status codes returned by the API.

# Errors

The API returns consistent error responses with an HTTP status code and a JSON body containing an error code and human-readable message.

## Error Response Format

All errors follow this structure:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Lead not found"
  }
}
```

| Field           | Type   | Description                               |
| --------------- | ------ | ----------------------------------------- |
| `error.code`    | string | A machine-readable error code             |
| `error.message` | string | A human-readable description of the error |

## HTTP Status Codes

| Code  | Status            | Description                                         |
| ----- | ----------------- | --------------------------------------------------- |
| `200` | OK                | Request succeeded                                   |
| `201` | Created           | Resource successfully created                       |
| `400` | Bad Request       | Invalid request body or missing required parameters |
| `401` | Unauthorized      | Missing, invalid, or revoked API key                |
| `403` | Forbidden         | API key does not have permission for this action    |
| `404` | Not Found         | The requested resource does not exist               |
| `429` | Too Many Requests | Rate limit exceeded                                 |
| `500` | Internal Error    | An unexpected error occurred on the server          |

## Error Code Reference

| Error Code     | HTTP Status | Description                |
| -------------- | ----------- | -------------------------- |
| `unauthorized` | 401         | Invalid or missing API key |
| `bad_request`  | 400         | Invalid request parameters |
| `not_found`    | 404         | Resource not found         |
| `rate_limited` | 429         | Rate limit exceeded        |
| `internal`     | 500         | Server error               |

## Common Error Scenarios

### Missing Authorization Header

```bash theme={null}
curl -X GET "https://api.reachedapp.com/v1/leads"
```

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header. Use: Bearer rchd_live_xxx"
  }
}
```

### Invalid JSON Body

```bash theme={null}
curl -X POST \
  "https://api.reachedapp.com/v1/leads" \
  -H "Authorization: Bearer rchd_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d 'invalid json'
```

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "Invalid JSON body"
  }
}
```

### Resource Not Found

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Lead not found"
  }
}
```

<Tip>
  Always check the `error.code` field programmatically rather than parsing the `message` string, as messages may change over time.
</Tip>