I
ILAL Docs
DashboardBack to Home

Error Codes Reference

Complete reference for all ILAL API error codes, organized by failure phase.

Unified Error Response Format

All error responses follow a consistent envelope with machine-readable codes and developer-actionable hints:

{
  "error": "Bad Request",              // HTTP status text
  "code": "UNSUPPORTED_TOKEN",         // Machine-readable error code
  "message": "tokenIn 0xabc... is not a supported token",
  "hint": "Supported tokens: WETH (0x4200...0006), tUSDC (0xa486...424D)",
  "phase": "preflight",                // Where the failure occurred
  "details": [...]                     // Optional: Zod validation errors
}
Phases
validation → auth → preflight → build → broadcast
Switch on
Use the code field for programmatic handling; hint for developer display.

Authentication (401 / 403)

API_KEY_MISSING401authMissing API Key
Description

No X-API-Key header in the request

How to Fix

Add the header: X-API-Key: ilal_live_xxx

API_KEY_FORMAT_INVALID401authInvalid API Key Format
Description

The key does not match the expected pattern

How to Fix

Expected format: ilal_{test|live}_{48 hex characters}

API_KEY_PREFIX_NOT_FOUND401authAPI Key Not Found
Description

No key with this prefix exists in the database

How to Fix

Verify the key is correct or create a new one in the Dashboard

API_KEY_HASH_MISMATCH401authAPI Key Verification Failed
Description

The key hash does not match any stored key

How to Fix

Use the exact key returned at creation time (shown only once)

API_KEY_INACTIVE401authAPI Key Deactivated
Description

This key has been revoked or deactivated

How to Fix

Reactivate or create a new key in the API Keys dashboard

API_KEY_EXPIRED401authAPI Key Expired
Description

This key has passed its expiration date

How to Fix

Generate a new API key in the dashboard

API_KEY_SCOPE_MISSING403authMissing Permission
Description

Your key lacks the required permission scope

How to Fix

Create a new key with the required permissions

JWT_MISSING401authMissing JWT
Description

Missing or malformed Authorization: Bearer header

How to Fix

Include Authorization: Bearer <accessToken> in headers

JWT_INVALID401authInvalid JWT
Description

The access token is invalid or expired

How to Fix

Obtain a new token via POST /auth/login or refresh token flow

INSTITUTION_OWNERSHIP_MISMATCH403preflightWallet Belongs to Another Account
Description

The userAddress/walletAddress is bound to a different ILAL account

How to Fix

Call POST /onboarding/register with this wallet to rebind it (demo mode)

Validation (400)

INVALID_PARAMS400validationRequest Validation Failed
Description

One or more request body fields failed validation

How to Fix

Check the "details" array in the response for specific field errors

INVALID_ADDRESS400validationInvalid Ethereum Address
Description

The address is not a valid 0x-prefixed 40-char hex string

How to Fix

Provide a valid checksummed Ethereum address

UNSUPPORTED_TOKEN400preflightToken Not Supported
Description

The token address is not in the current supported token whitelist

How to Fix

Use supported tokens: WETH (0x4200...0006) or tUSDC (0xa486...424D)

Preflight / Session (412)

SESSION_NOT_ACTIVE412preflightSession Not Active
Description

No active compliance session for this wallet. Returned by default from /defi/swap and /defi/liquidity — transaction would revert on-chain. Add ?buildOnly=true to suppress and get unsigned TX anyway.

How to Fix

Testnet: POST /onboarding/activate-session-demo | Production: POST /verify (ZK proof flow)

ALLOWANCE_INSUFFICIENT200preflightInsufficient Allowance (Warning)
Description

Token allowance for the router/manager is less than the requested amount

How to Fix

Approve the token to the SwapRouter or PositionManager before broadcasting

Rate Limiting (429)

RATE_LIMIT_EXCEEDED429authRate Limit Exceeded
Description

Too many requests per minute

How to Fix

Wait for the rate limit window to reset (60s) or upgrade your plan

Build / Broadcast (400 / 500)

BUILD_FAILED400buildTransaction Build Failed
Description

Could not construct the transaction calldata

How to Fix

Check token addresses, amounts, and tick ranges

INTERNAL_ERROR500buildInternal Server Error
Description

Unexpected error during processing

How to Fix

Retry later. If persistent, contact support with the error message

Deprecated Configurations

0x036CbD53842c5426634e7929541eC2318f3dCF7e — Circle USDC (pool drained, replaced by tUSDC)

0xe633220f15932428FcA60A1A2C2C48797A180A80 — ComplianceHook v1 (deprecated)

0xdD37A28e15A9592eAAd3f7Df0Ad36e374Af68A80 — ComplianceHook v2 (deprecated)

If your code references any of the above addresses, update to the current configuration shown on the docs overview page.

Error Handling Best Practices

  • 1.Switch on the code field (e.g. SESSION_NOT_ACTIVE) — not the HTTP status or message
  • 2.Check phase to know which stage failed: validation → auth → preflight → build → broadcast
  • 3.Show the hint field to developers/operators — it contains actionable next steps
  • 4.For 429 errors, wait for the retryAfter value before retrying
  • 5.Before broadcasting, call GET /defi/preflight/:address to check session, balances, and allowances in one call