Skip to main content
Use this page as a lookup when the AIR Kit REST API returns a specific HTTP status, or when an SDK method rejects with an AirKitError. For higher-level JWT / JWKS / CORS / rate-limit guidance, see Common issues.

API error codes

These errors apply to the AIR Kit REST API (e.g. Issuance API).

SDK errors

Every AirService method rejects with an AirKitError. Each error carries a stable code in "domain/reason" form and a coarse category. Rely on these rather than on err.name or err.message.

The error object

Categories

  • user — the user cancelled, rejected, or hit something the AIR UI already explained. Usually do nothing, or just stop the flow.
  • session — the session or Partner JWT is no longer valid. Mint a fresh Partner JWT or sign the user in again.
  • config — an integration problem, such as bad parameters, a feature that isn’t enabled, or an unsupported chain. Fix the call or your Developer Dashboard settings.
  • network — transient. It is safe to offer a retry.
  • internal — something failed on AIR’s side. Show a generic error and log code and eventId.
New codes may be added in minor releases. Always fall back on category so an unknown code is still handled.
showReceiveUI() resolves, rather than rejects, when the user closes it. The other show*UI() methods reject when the user closes them.

SDK error codes

The Previous name column is what err.name returned before this release, and still returns. Use it to map existing switch (err.name) code to the new codes.

SDK and configuration

Authentication

Wallet

Credentials

Recovery

User input and environment

Popups

Network and internal

Provider (EIP-1193) errors

airService.provider.request(...) rejects with a standard EIP-1193 error, so wagmi, viem, and ethers keep working unchanged.

Migrating from err.name

AirServiceError and err.name still work, so existing code keeps running. Both are deprecated and will be removed in the next major release. See the release notes for the full change.