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

# Errors

> API v2 error format and codes

# Errors

API v2 returns structured error objects inside an `error` key.

## Error shape

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Some fields are invalid. Please check and try again.",
    "details": {
      "issues": [
        { "field": "email", "message": "Please enter a valid email address." }
      ]
    }
  }
}
```

| Field     | Description                                             |
| --------- | ------------------------------------------------------- |
| `code`    | Machine-readable error code                             |
| `message` | Human-readable summary                                  |
| `details` | Optional extra context (validation issues, retry hints) |

## Error codes

| Code                    | HTTP Status | Description                            |
| ----------------------- | ----------- | -------------------------------------- |
| `UNAUTHORIZED`          | 401         | Missing or invalid API key             |
| `FORBIDDEN`             | 403         | Valid key but insufficient permission  |
| `NOT_FOUND`             | 404         | Resource does not exist                |
| `VALIDATION_ERROR`      | 400         | Invalid request body or parameters     |
| `BAD_REQUEST`           | 400         | General bad request                    |
| `CONFLICT`              | 409         | Operation conflicts with existing data |
| `TOO_MANY_REQUESTS`     | 429         | Rate limit exceeded                    |
| `INTERNAL_SERVER_ERROR` | 500         | Unexpected server error                |

## Validation errors

When request validation fails, `details.issues` lists each problem:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Some fields are invalid. Please check and try again.",
    "details": {
      "issues": [
        { "field": "firstName", "message": "Required" },
        { "message": "Unknown field: foo. Only documented fields and cf_* keys are allowed." }
      ]
    }
  }
}
```

## Retry guidance

* **429** — Back off and retry after the window in `RateLimit-Reset`
* **500** — Retry with exponential backoff
* **400 / 409** — Fix the request; retrying without changes will fail