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

# Error Handling

> Handle Prontiq API errors, retries, and request-id tracing.

All public data API errors use a JSON envelope with a machine-readable code and
a request id.

```json theme={null}
{
  "error": {
    "code": "MACHINE_READABLE_CODE",
    "message": "Human-readable explanation",
    "status": 429,
    "request_id": "req_abc123...",
    "details": {}
  }
}
```

`details` is optional and depends on the error.

## Public data API errors

| Code                  | HTTP | Meaning                                                           |
| --------------------- | ---- | ----------------------------------------------------------------- |
| `MISSING_API_KEY`     | 401  | The request did not include `X-Api-Key`.                          |
| `INVALID_API_KEY`     | 401  | The key is unknown, inactive, or invalid.                         |
| `INVALID_PARAMETERS`  | 400  | Query parameters failed public endpoint validation.               |
| `PRODUCT_NOT_ALLOWED` | 403  | The authenticated account cannot access the requested API family. |
| `NOT_FOUND`           | 404  | The requested resource was not found.                             |
| `QUOTA_EXCEEDED`      | 429  | Request-time quota enforcement rejected the request.              |
| `RATE_LIMITED`        | 429  | The request exceeded burst or route protection limits.            |
| `INTERNAL_ERROR`      | 500  | The API failed unexpectedly.                                      |

## Parameter validation

Public Address endpoints validate required and constrained query parameters
before running a search. Invalid requests return `400 INVALID_PARAMETERS`.

For example, calling autocomplete without `q` returns the standard error
envelope with field-level details:

```json theme={null}
{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid query parameters",
    "status": 400,
    "request_id": "req_abc123...",
    "details": {
      "q": ["Required"]
    }
  }
}
```

`details` uses field names as keys. Each value is an array of validation
messages for that field. The exact message text can change with validation
library updates, so clients should branch on `error.code`, `error.status`, and
the presence of a field key rather than matching message strings.

## Private or forward-contract errors

These codes can appear on private console/account routes or are reserved for
forward-compatible contracts. They are listed here so integrations can classify
them if encountered, but they are not all public data API outcomes.

| Code                  | HTTP | Meaning                                                             |
| --------------------- | ---- | ------------------------------------------------------------------- |
| `KEY_LIMIT_EXCEEDED`  | 403  | A console key-management action would exceed the current key limit. |
| `UNAUTHORIZED`        | 401  | A private route is missing a valid Clerk session.                   |
| `ORG_REQUIRED`        | 403  | A private route needs an active Clerk organization.                 |
| `INVALID_SIGNATURE`   | 400  | A webhook signature did not verify.                                 |
| `SERVICE_UNAVAILABLE` | 503  | A dependency is unavailable or a circuit is open.                   |

## Retry guidance

* Retry `RATE_LIMITED` after `Retry-After` when that header is present.
* Do not automatically retry `QUOTA_EXCEEDED`; direct the user to account
  billing or support.
* Retry `SERVICE_UNAVAILABLE` with exponential backoff and jitter.
* Do not retry `MISSING_API_KEY`, `INVALID_API_KEY`, `INVALID_PARAMETERS`, or
  `PRODUCT_NOT_ALLOWED` without changing credentials, parameters, or account
  access.
* Do not retry `NOT_FOUND` for the same resource id unless upstream data has
  changed or the id came from stale client state.
* Treat `INTERNAL_ERROR` as retryable only with bounded retries.

## Request-id tracing

Every response includes `X-Request-Id`. Error responses include the same value
as `error.request_id`.

When contacting support, include:

* the request id;
* endpoint path and method;
* timestamp;
* account or organization name;
* sanitized client context.

Do not send API keys, request bodies containing sensitive user data, or raw
customer data in support messages.