Error Codes Reference

Complete reference for all ILAL API error codes

Error Response Format

All error responses follow a consistent format:

{
  "error": "Error Title",
  "code": "AUTH_001",
  "message": "Detailed error description",
  "statusCode": 401,
  "retryAfter": 60  // Only present on 429 errors
}

Authentication Errors (4xx)

AUTH_001401Missing API Key

Description

The X-API-Key header is missing from the request

Solution

Add X-API-Key: YOUR_API_KEY to the request headers

AUTH_002401Invalid API Key

Description

The API Key provided is invalid or has been revoked

Solution

Verify the API Key is correct, or create a new one in the Dashboard

AUTH_003403Forbidden

Description

Your API Key does not have permission to access this endpoint

Solution

Upgrade your plan or contact the administrator for higher permissions

AUTH_004401Token Expired

Description

The access token has expired

Solution

Use the refresh token to obtain a new access token

Request Errors (4xx)

REQ_001400Invalid Request Body

Description

The request body is malformed or missing required fields

Solution

Ensure the request body is valid JSON and includes all required fields

REQ_002400Invalid Address

Description

The Ethereum address format is invalid

Solution

Ensure the address is a valid Ethereum address (0x-prefixed, 40 hex characters)

REQ_003400Invalid Proof

Description

The ZK Proof is malformed or failed verification

Solution

Check proof data integrity and ensure it was generated with the correct proving system

REQ_004404Session Not Found

Description

The specified session ID does not exist

Solution

Call /verify first to create a session, or check that the sessionId is correct

REQ_005409Session Expired

Description

The session has expired

Solution

Call /verify again to create a new session

Rate Limiting (429)

RATE_001429Rate Limit Exceeded

Description

You have exceeded the per-minute request limit

Solution

Wait for retryAfter seconds before retrying, or upgrade your plan for a higher limit

RATE_002429Monthly Quota Exceeded

Description

You have exceeded the monthly API call limit

Solution

Wait for the quota to reset next month, or upgrade your plan

Server Errors (5xx)

SRV_001500Internal Server Error

Description

An unexpected server error occurred

Solution

Please retry later. If the issue persists, contact support

SRV_002502Bad Gateway

Description

An upstream service is unavailable

Solution

Please retry later — this typically resolves within minutes

SRV_003503Service Unavailable

Description

The service is temporarily unavailable (under maintenance)

Solution

Check the status page and wait for maintenance to complete

Error Handling Best Practices

•Always check the HTTP status code, not just the response body
•For 429 errors, use the retryAfter field for exponential backoff
•For 5xx errors, implement automatic retry logic (up to 3 retries recommended)
•Log the error code field from all error responses for debugging and support tickets
•Use the SDK's built-in error types for granular error handling (recommended)