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

# Authentication and errors

> Use an organization API key, handle endpoint-specific errors, and pace API requests

Both APIs use `https://api.aws53.cloud` as the base URL. Create or manage your organization API key in **Settings > API Keys** and send it in the `X-API-Key` header for operations that support API-key authentication.

```http theme={null}
X-API-Key: YOUR_ORGANIZATION_API_KEY
```

Keys are scoped to an organization. Use resource IDs from that organization. Regenerating a key invalidates the previous one; update every backend that uses it. Do not place keys in browser code or pixel URLs.

## Authentication by API

| API area                                                   | Authentication                                                        |
| ---------------------------------------------------------- | --------------------------------------------------------------------- |
| Identification API                                         | Organization API key                                                  |
| Orbit topic discovery and filter catalog                   | Public; see each endpoint for optional authentication and rate limits |
| Orbit audience definitions, runs, results, and topic lists | Organization API key or supported Bearer authentication               |
| Orbit integrations, destinations, and deliveries           | See the access discrepancy below before integrating                   |

Do not send an `sk_...` API key as a Bearer token.

<Warning>
  The hosted Orbit specification currently conflicts on integration, destination, and delivery authentication: its security declarations allow API keys, but its operation descriptions require a non-viewer member using Bearer authentication. API-key support for these operations needs confirmation from Leadpipe before you rely on it. The generated authentication control alone does not resolve this discrepancy.
</Warning>

## Read the endpoint's error response

The generated endpoint reference defines the status codes and response body for each operation. Identification and Orbit do not use one universal error envelope.

| Status | Action                                                                                                   |
| ------ | -------------------------------------------------------------------------------------------------------- |
| `400`  | Correct the request using the endpoint schema and returned validation details.                           |
| `401`  | Check the header and current key.                                                                        |
| `403`  | Check key revocation, organization status, selected-resource access, and feature access.                 |
| `404`  | Check the resource ID and organization.                                                                  |
| `409`  | Resolve the endpoint-specific conflict before retrying.                                                  |
| `429`  | Wait as instructed by the response headers and reduce request frequency.                                 |
| `5xx`  | Capture a redacted response and request ID when present; limit retries and escalate persistent failures. |

For an Orbit results read, `202` means the run is still queued or running. Failed or cancelled runs return a conflict. See the [polling example](/orbit-api/examples).

## Rate limits and retries

For Identification visitor reads and qualification queries, use `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`. The reset value is in seconds. A `429` response also documents `Retry-After` in seconds. Do not hardcode an allowance from another endpoint.

Orbit has endpoint-specific allowances. Public catalog requests and site analysis have different authentication behavior; see [Find topics](/orbit-api/find-topics#authentication-and-rate-limits).

Use bounded retries for reads. Before retrying a write, check whether it supports safe repetition. Orbit run creation supports `Idempotency-Key`: reuse the same key for retries of the same intended run, and choose a new key for a new run. Do not assume that every write accepts that header.

For troubleshooting, record the method, path, HTTP status, and request ID when available. Remove API keys and personal visitor data from shared logs.