Response formats depend on the endpoint
Integration APIs retain several compatible error formats. Anerror 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.
- 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_hintsays what to do next. The message is fixed and never names the cause. - Request error:
400 invalid_request. AIsa answers400when the request is wrong: the gateway’s contract check failed, or the data source rejected the request’s input.paramnames the parameter when it is known (always one of the parameters you sent or a path parameter);missingandunsupportedlist 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,
messageis a fixed text from AIsa,retryableisfalse, andretry_hintisnever. - No
502or504. AIsa never returns502or504on these operations. A502or504, or an HTML orapplication/problem+jsonerror page, withoutX-Request-IDcomes from the network edge in front of AIsa, not from AIsa. Retry it after a delay. - Request ID.
X-Request-IDis always present and equalserror.request_id. It is an opaque string, so do not parse it. It can start withreq_when the request was rejected before a charge was reserved, and withimc_afterwards. - Cost header.
X-AISA-Customer-Cost-Micros-USD: 0on 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 the503above 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, readhttps://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
HTTP401
Parameters: native request
HTTP400
Budget: estimate exceeds cap
HTTP402
Idempotency: completed request
HTTP409
Idempotency: Similarweb compatibility
HTTP409
Upstream: native transport failure (outside the standard envelope)
HTTP502
Upstream: managed transport failure
HTTP503
Dependency: billing timeout
HTTP503; X-Request-ID: example-request-id
Configuration: invalid billing configuration
HTTP503
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 onafter_delay; keep the request ID and do not resend onreconcile_first; do not retry unchanged onnever. - A
retryablehint 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.