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.

The examples below describe gateway-generated Integration API errors. OpenAI-compatible and Anthropic-compatible endpoints have their own protocol shapes. 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.

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	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	Native transport failure can be 502; a managed Similarweb transport failure can be 503 provider_unavailable; a Provider response can pass through	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. Honor Retry-After when it is actually returned.

Missing credentials can follow different paths

For GET /apis/v1/similarweb/website/traffic-engagement, the following responses have been observed with otherwise valid request parameters:

Credential and mode	Observed response
No API key, ordinary execution request	404 with {"error":"api endpoint not found"}
No API key, X-AISA-Cost-Mode: quote	401 with a structured authentication error
Invalid API key, ordinary execution request	401 with top-level code: invalid_api_key

For this path, a 404 without credentials does not establish that the endpoint is absent. Supply the AISA credential before diagnosing route availability, and distinguish quote mode from execution. These observations do not promise the same authentication status or error layout for every endpoint.

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

{
  "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

{
  "error": "request does not match the endpoint contract"
}

Budget: estimate exceeds cap

HTTP 402

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

Idempotency: completed request

HTTP 409

{
  "error": {
    "code": "request_already_completed",
    "message": "An identical request is already complete.",
    "retryable": false
  }
}

Idempotency: Similarweb compatibility

HTTP 409

{
  "error": {
    "code": "similarweb_request_already_completed",
    "message": "An identical request is already complete.",
    "retryable": false
  }
}

Upstream: native transport failure

HTTP 502

{
  "error": "provider request failed"
}

Upstream: managed transport failure

HTTP 503

{
  "error": {
    "code": "provider_unavailable",
    "message": "Similarweb is temporarily unavailable."
  }
}

Dependency: billing timeout

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

{
  "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

{
  "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; an error or missing cost header does not establish zero debit.

Retry guidance

• Fix credentials, parameters, and budget limits before retrying the corresponding rejection.
• 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 [e-mail] 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.