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

> ## Agent Instructions
> - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative.
> - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key.
> - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste.
> - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`.
> - Spending: docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP `search`, `list_categories`, `get_details`, `batch_quote`, and the `account` operation are free. Quote the exact calls before running them (MCP `batch_quote`, CLI `aisa quote --json`). If the quote reports `auto_execute_eligible: true`, run it unless the user set a tighter limit or asked only for a quote. Otherwise, tell the user in one message the planned calls, the quoted price, and a total USD budget for the task, then wait for approval. Direct HTTP calls follow the stricter rule at https://aisa.one/docs/get-started/cli.md#direct-http-fallback. Do not make paid calls to test availability. Full rule: https://aisa.one/llms.txt

# Error Codes

> Integration API error formats, six diagnostic categories, and safe retry guidance.

## Response formats depend on the endpoint

Integration APIs retain several compatible error formats. An `error` value can be a string or an object; a machine-readable `code` may be at the top level or inside that object. Do not require `type`, `code`, or `request_id` on every error. Operations that use the [standard error envelope](#standard-error-envelope) always return an object.

The examples below describe gateway-generated Integration API errors. OpenAI-compatible and Anthropic-compatible endpoints have their own protocol shapes. Outside the standard envelope, ordinary Provider responses can preserve the upstream status, body, and content type, including non-JSON errors. Check the HTTP status and content type before parsing a response.

For support, retain `X-Request-ID` when returned, and `request_id` when present in the body. Their presence and location depend on the error path; the examples do not promise that every rejection includes both. On operations that use the standard envelope, every error AIsa writes carries both, and they are equal.

## Standard error envelope

Some Integration API operations use one standard error envelope. You can recognize it in the body: `error` is an object carrying `code`, `message`, `retryable`, `retry_hint`, and `request_id`. On these operations, AIsa no longer passes through a supplier's status code, error code, or message.

```json theme={null}
{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable.",
    "retryable": true,
    "retry_hint": "after_delay",
    "request_id": "example-request-id"
  }
}
```

This example illustrates the envelope; the request ID is illustrative.

* **Supplier-side failure: `503 service_unavailable`.** Every failure on the supplier's side has the same public answer: a rate limit, temporary unavailability, a timeout, an upstream error, an unusable response, or a problem with AIsa's own upstream account. `retry_hint` says what to do next. The message is fixed and never names the cause.
* **Request error: `400 invalid_request`.** AIsa answers `400` when the request is wrong: the gateway's contract check failed, or the data source rejected the request's input. `param` names the parameter when it is known (always one of the parameters you sent or a path parameter); `missing` and `unsupported` list parameters when known.
* **Not found: `404 not_found`.** The lookup completed and found nothing, for example an unknown profile, person, or company. Do not retry the same request. It is not charged.
* **Not accessible: `403 target_not_accessible`.** The requested target exists but is private or restricted. Do not retry the same request.
* In all three cases, `message` is a fixed text from AIsa, `retryable` is `false`, and `retry_hint` is `never`.
* **No `502` or `504`.** AIsa never returns `502` or `504` on these operations. A `502` or `504`, or an HTML or `application/problem+json` error page, without `X-Request-ID` comes from the network edge in front of AIsa, not from AIsa. Retry it after a delay.
* **Request ID.** `X-Request-ID` is always present and equals `error.request_id`. It is an opaque string, so do not parse it. It can start with `req_` when the request was rejected before a charge was reserved, and with `imc_` afterwards.
* **Cost header.** `X-AISA-Customer-Cost-Micros-USD: 0` on an error confirms that the request was not charged. The header is absent while the outcome is pending reconciliation (`reconcile_first`).
* **Timeouts.** When an operation publishes `x-aisa-latency.timeout_seconds`, it answers within that many seconds, with the `503` above when time runs out; set your client timeout a little above it. Operations without it have no fixed answer budget.

| `retry_hint` | `retryable` | Meaning and next action |
| - | - | - |
| `after_delay` | `true` | Transient condition: rate limit, temporary unavailability, timeout, or the call was not dispatched. Retry after a short delay, with bounded exponential backoff and jitter. |
| `reconcile_first` | `false` | The call was dispatched, and its outcome and charge are not known yet. Do not resend automatically. Look the outcome up with `GET /v1/settlements/{request_id}` (the `X-Request-ID`), or `GET /v1/settlements?idempotency_key=<key>` if you sent one: `state` is `pending`, `charged`, or `not_charged`. |
| `never` | `false` | Retrying the same request will not help. Correct the request (`400`), or treat the call as failed. |

### Migration of public codes

| Before | Now, on operations with the standard envelope |
| - | - |
| String envelope `{"error":"..."}` | The object envelope above |
| `502` `provider request failed`, `provider response could not be accounted`, or `provider response cannot be reconciled` | `503 service_unavailable` |
| `provider_unavailable`, `upstream_rate_limited`, `upstream_temporarily_unavailable`, `upstream_request_failed`, `provider_accounting_pending`, `provider_capacity_exhausted`, or a supplier-specific code | `503 service_unavailable`; `retry_hint` distinguishes the cases |
| Supplier `429` passed through | `503 service_unavailable` with `retry_hint: after_delay` |
| Supplier `4xx` passed through with the supplier's message | `404 not_found` for a lookup that found nothing, `403 target_not_accessible` for a private target, `400 invalid_request` (with `param` when known) for rejected input; any other rejection is `503 service_unavailable` |
| No cost header on errors | `0` when confirmed not charged; absent while pending reconciliation |

Operations outside the standard envelope keep the formats described in the rest of this page.

## Six diagnostic categories

| Category | Typical Integration API response | Next action |
| - | - | - |
| Authentication | `401`: `missing_api_key`, `invalid_api_key`, `api_key_disabled`, or `expired_api_key`; authentication dependency failure can be `503 authentication_unavailable` | Correct the AISA credential or investigate the authentication dependency. |
| Parameters | `400`, sometimes a string-only error; managed product validation can return a structured code; the standard envelope uses `400 invalid_request` with `param` | Correct the request against the endpoint's contract. |
| Budget | `402`: `estimated_price_exceeds_max_price`, `insufficient_api_key_balance`, or `insufficient_wallet_balance` | Review the spending limit and eligible balance; an estimate is not a settled charge. |
| Idempotency | `409`: `request_in_progress`, `request_already_completed`, or `idempotency_conflict`; Similarweb retains prefixed compatibility codes | Check the original operation. Do not use a new key merely to bypass a conflict. |
| Upstream | Standard envelope: `503 service_unavailable` with `retry_hint`, never `502` or `504`. Elsewhere: native transport failure can be `502`; a managed Similarweb transport failure can be `503 provider_unavailable`; a Provider response can pass through | Follow `retry_hint` when present. Otherwise, establish whether dispatch or execution occurred before repeating a request. |
| Configuration or dependency | `503`: `metered_v2_billing_config_invalid`, `metered_v2_billing_dependency_timeout`, or `metered_v2_billing_dependency_unavailable`; Similarweb can use the `similarweb_billing_` prefix | Distinguish configuration repair from transient dependency recovery. |

A `503` does not by itself identify an upstream failure. A `404` can refer to a route or an upstream resource; authentication can run before route lookup, so a missing credential is not proof that a route is absent. `403`, `422`, and `429` remain endpoint-specific: do not assume a universal code list or rate-limit headers. On the standard envelope, a supplier's rate limit is `503` with `retry_hint: after_delay`, not `429`. Honor `Retry-After` when it is actually returned.

## Requests without a credential

A request without any AISA credential gets one of two answers, decided by the route, never by the HTTP method. Observed on 2026-10-20:

| Route (no credential) | Response |
| - | - |
| Routes that carry a per-request machine-payment (MPP) quote, for example `GET /apis/v1/fred/series`, `GET /apis/v1/agentmail/api-keys`, or `POST /apis/v1/querit/search` | `402` with an MPP payment challenge |
| Every other route, including unknown paths, `GET /v1/models`, `GET /v1/credits/balance`, other data routes such as `GET /apis/v1/similarweb/website-traffic-snapshot` or `POST /apis/v1/exa/search`, and `/v1` model routes such as `POST /v1/chat/completions` | `401` with top-level `code: missing_api_key` |
| Any route with an **invalid** key | `401` with `code: invalid_api_key` |

A credential-less `402` is the gateway's offer to be paid per request through MPP, not a statement that a balance is low: send the AISA key, or complete the challenge. A `401 missing_api_key` means only that no credential was sent; it does not say whether the route exists. In cost-quote mode (`X-AISA-Cost-Mode: quote`) the authentication error is an object inside `error`, for example `{"error":{"code":"invalid_api_key",...}}`.

Do not use `GET /v1/models` as proof of business access: success there is only a transport check. Verify an integration with a free protected call instead (`GET /v1/credits/balance` over HTTP, the `account` operation over MCP, `aisa balance` with the CLI).

## Documentation and sales-source availability

The Website's contract and sales-data endpoints report source availability separately from Integration API execution errors.

To inspect a published contract, read `https://aisa.one/api/contracts/version`. Its `contentHash` identifies the OpenAPI bytes and `docsRevision` identifies the immutable Docs input. Request `/api/contracts/source?hash=<contentHash>&bundled=1` for those bytes, or `/api/contracts/source?hash=<contentHash>&operation_id=<operationId>` for one operation. A mismatched hash returns `409`; unavailable verified bundled content can return `503`. Check the response's `X-AISA-Contract-Hash` and `X-AISA-Docs-Revision` against the selected version. `mode: formal` describes the bundled declarations; it does not establish that dynamic prices, availability, or every consumer are fresh.

A definition marked `pending` remains incomplete. Do not invent missing request fields or treat an unavailable request definition as a ready-to-call contract. A pending response definition remains unknown even when the existing endpoint can be called.

The sales JSON endpoint `/api/sales-api-data` can return HTTP `503` with `freshness: unavailable` and `reason_code: verified_sales_source_unavailable` when it cannot acquire a verified sales snapshot. This response is a documentation/source-availability result; it is not evidence that a Provider request was executed, authentication failed, or a charge settled. Retain a previously verified snapshot only with its original observation time and an explicit stale state; never relabel a static snapshot as fresh. Recheck the source and release identities before treating recovery as current data.

## Observed gateway examples

These examples preserve the actual error shapes. The request ID is illustrative.

### Authentication: API key

HTTP `401`

```json theme={null}
{
  "code": "invalid_api_key",
  "error": "AISA API key is invalid. Check that you copied the complete key and are using an AISA key, not an upstream provider key.",
  "request_id": "example-request-id"
}
```

### Parameters: native request

HTTP `400`

```json theme={null}
{
  "error": "request does not match the endpoint contract"
}
```

### Budget: estimate exceeds cap

HTTP `402`

```json theme={null}
{
  "error": {
    "code": "estimated_price_exceeds_max_price",
    "message": "The estimated request price exceeds the configured maximum.",
    "retryable": false
  }
}
```

### Idempotency: completed request

HTTP `409`

```json theme={null}
{
  "error": {
    "code": "request_already_completed",
    "message": "An identical request is already complete.",
    "retryable": false
  }
}
```

### Idempotency: Similarweb compatibility

HTTP `409`

```json theme={null}
{
  "error": {
    "code": "similarweb_request_already_completed",
    "message": "An identical request is already complete.",
    "retryable": false
  }
}
```

### Upstream: native transport failure (outside the standard envelope)

HTTP `502`

```json theme={null}
{
  "error": "provider request failed"
}
```

### Upstream: managed transport failure

HTTP `503`

```json theme={null}
{
  "error": {
    "code": "provider_unavailable",
    "message": "Similarweb is temporarily unavailable."
  }
}
```

### Dependency: billing timeout

HTTP `503`; `X-Request-ID: example-request-id`

```json theme={null}
{
  "error": {
    "code": "metered_v2_billing_dependency_timeout",
    "message": "The billing dependency timed out. Retry the request.",
    "request_id": "example-request-id",
    "retryable": true
  }
}
```

### Configuration: invalid billing configuration

HTTP `503`

```json theme={null}
{
  "error": {
    "code": "metered_v2_billing_config_invalid",
    "message": "The Metering V2 billing configuration is invalid.",
    "retryable": true
  }
}
```

Cost-quote authentication errors use an object inside `error` with `code` and `message`, rather than the top-level authentication layout above. Validation failures for a supplied API key also return `request_id`; rejection when credentials are missing can omit it. Preserve an ID when returned, without requiring one on every quote rejection. Consult the endpoint's quote contract when handling that mode.

For reported charges, see [Settled call cost](https://aisa.one/docs/api-reference.md#settled-call-cost); outside the standard envelope, an error or missing cost header does not establish zero debit. On the standard envelope, a cost header of `0` on an error confirms that the request was not charged.

## Retry guidance

* Fix credentials, parameters, and budget limits before retrying the corresponding rejection.
* When the error carries `retry_hint`, follow it: retry after a delay on `after_delay`; keep the request ID and do not resend on `reconcile_first`; do not retry unchanged on `never`.
* A `retryable` hint does not guarantee that execution had no side effects, that the retry is free, or that an endpoint supports idempotency. Even repeated GET or chat requests can incur charges.
* On `409`, inspect the original operation and follow that endpoint's idempotency rules. Keep the same key and payload when those rules require it; changing the key can create a second operation.
* For a transient failure, first establish that repetition is safe. Respect an available `Retry-After`; otherwise use bounded exponential backoff with jitter. Do not blindly replay an ambiguous Provider create or a billed call.
* A persistent configuration error needs operator investigation, not an unbounded retry loop. Preserve the original status and response when a Provider error does not match these examples.

## Getting help

Send [developer@aisa.one](mailto:developer@aisa.one) the approximate UTC time, HTTP method and public path, status, returned error code (if any), request ID (if available), and a minimal redacted reproduction. Do not include API keys or other credentials.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.