Skip to main content

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 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.
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.

Migration of public codes

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

Six diagnostic categories

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: 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

Parameters: native request

HTTP 400

Budget: estimate exceeds cap

HTTP 402

Idempotency: completed request

HTTP 409

Idempotency: Similarweb compatibility

HTTP 409

Upstream: native transport failure (outside the standard envelope)

HTTP 502

Upstream: managed transport failure

HTTP 503

Dependency: billing timeout

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

Configuration: invalid billing configuration

HTTP 503
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; 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 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.