Error Handling

The API uses standard HTTP status codes and returns structured error responses.

Error Response Format

{
  "error": {
    "code": "error_code",
    "message": "A human-readable description of the error."
  }
}

HTTP Status Codes

Status	Meaning
200	Success
201	Resource created
204	Success (no content)
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid authentication
402	Payment required — insufficient token balance
403	Forbidden — insufficient permissions
404	Not found
409	Conflict — resource already exists (e.g., duplicate key name)
429	Rate limit exceeded
500	Internal server error

Common Error Codes

Authentication Errors (401)

Code	Description
missing_authentication	No API key or JWT provided
invalid_api_key	Key format invalid or key not found
expired_api_key	Key has passed its expiration date
revoked_api_key	Key has been deactivated

Authorization Errors (403)

Code	Description
insufficient_permissions	Key lacks required permission for this endpoint

Billing Errors (402)

Code	Description
insufficient_balance	Not enough tokens — top up your account

Validation Errors (400)

Code	Description
invalid_request	Request body is malformed
invalid_address	Wallet address format is invalid
invalid_key_name	Key name is empty, too long, or contains invalid characters
max_keys_exceeded	Maximum of 10 API keys per user reached

Rate Limit Errors (429)

Code	Description
rate_limit_exceeded	Too many requests — check Retry-After header

Handling Errors

import requests

response = requests.get(
    "https://mvp.amlyou.com/api/analysis/wallet/0x...",
    headers={"X-API-Key": "ak_live_..."}
)

if response.status_code == 200:
    data = response.json()
elif response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 60))
    time.sleep(retry_after)
elif response.status_code == 402:
    print("Insufficient balance — please top up")
else:
    error = response.json().get("error", {})
    print(f"Error {error.get('code')}: {error.get('message')}")

const response = await fetch(
  "https://mvp.amlyou.com/api/analysis/wallet/0x...",
  { headers: { "X-API-Key": "ak_live_..." } }
);

if (!response.ok) {
  const { error } = await response.json();

  if (response.status === 429) {
    const retryAfter = response.headers.get("Retry-After");
    // Wait and retry
  } else {
    console.error(`${error.code}: ${error.message}`);
  }
}