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

# Error reference

> HTTP status codes, error codes, and when each is returned.

Every error uses the same envelope; `details` is present only when useful.

```json theme={null}
{
 "error": {
  "code": "validation_error",
  "message": "companyWebsite: Invalid url; alertEmails.0: Invalid email"
 }
}
```

Validation messages list every failing field as `path: reason`, so a client can fix everything in one round trip.

| HTTP | `code`                                  | When                                                                                                                                                                                                                        |
| ---- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `validation_error`                      | Invalid or missing fields (message lists each), bad enum value, bad date, `since` ≥ `until`, bad `view`, non-numeric `limit`, malformed ID, invalid `Idempotency-Key`, exact and fuzzy filters sent together, empty `PATCH` |
| 400  | `invalid_json`                          | Request body is not valid JSON                                                                                                                                                                                              |
| 400  | `invalid_cursor`                        | Cursor was tampered with or malformed                                                                                                                                                                                       |
| 401  | `unauthorized`                          | Missing, malformed, unknown, revoked or expired API key                                                                                                                                                                     |
| 403  | `insufficient_scope`                    | Key lacks the scope the endpoint needs                                                                                                                                                                                      |
| 404  | `not_found`                             | Unknown ID, or an ID from another organisation. Unknown paths also return 404                                                                                                                                               |
| 404  | `entity_not_found` / `source_not_found` | Fuzzy lookup matched nothing                                                                                                                                                                                                |
| 405  |                                         | HTTP method not supported on that path                                                                                                                                                                                      |
| 409  | `ambiguous_entity` / `ambiguous_source` | Fuzzy lookup matched several companies; `details.candidates` lists them                                                                                                                                                     |
| 409  | `idempotency_conflict`                  | `Idempotency-Key` reused with a different body                                                                                                                                                                              |
| 409  | `idempotency_in_progress`               | The original request with that key is still running                                                                                                                                                                         |
| 409  | `refresh_in_progress`                   | A tracker run is already in progress                                                                                                                                                                                        |
| 409  | `entity_paused`                         | Refresh requested for a paused entity                                                                                                                                                                                       |
| 429  | `rate_limited`                          | Per-key rate limit exceeded; see `Retry-After` and `details`                                                                                                                                                                |
| 500  | `internal_error`                        | Unexpected server error                                                                                                                                                                                                     |
| 500  | `auth_unavailable`                      | The key could not be verified (transient)                                                                                                                                                                                   |
| 502  | `enrichment_failed`                     | Draft enrichment failed or returned an invalid result                                                                                                                                                                       |
| 502  | `refresh_failed`                        | The tracker backend could not queue a refresh                                                                                                                                                                               |
| 503  | `idempotency_unavailable`               | Idempotency storage was unavailable; retry later                                                                                                                                                                            |