Axis API Base URL, Request Format, and Error Handling

Every Axis API request targets a versioned base URL. Learn the two route namespaces, standard error shape, and how to handle common HTTP status codes.

Axis exposes two route namespaces that reflect the natural split between user-facing operations (auth and onboarding) and agent-facing operations (wallets, payments, and ledger). Both namespaces live under the same base URL and follow the same JSON conventions — understanding which namespace to target and what to expect when something goes wrong will save you debugging time early.

Route namespaces

/v1/ — Auth, onboarding, and wallet data

The /v1/ namespace handles identity: signing users up, issuing session tokens, and bootstrapping their first wallet through the onboarding flow. It also exposes read endpoints for wallet stats and transaction history scoped to the authenticated session.

Method	Path	Description
POST	/v1/auth/signup	Create a new user account
POST	/v1/auth/login	Exchange credentials for a session token
POST	/v1/auth/logout	Invalidate the current session token
POST	/v1/onboarding	Run the post-signup onboarding flow
GET	/v1/wallets/:id/stats	Fetch aggregate stats for a wallet
GET	/v1/wallets/:id/transactions	List transactions scoped to a wallet

/api/ — Wallets and payments

The /api/ namespace is where wallets are provisioned and agents submit payment intents. Wallet CRUD routes require a session token; the payment intent route requires a wallet API key.

Method	Path	Description
POST	/api/onboarding	Alternative onboarding route (also valid)
POST	/api/wallets	Provision a new wallet
GET	/api/wallets/:walletId	Fetch a wallet by ID
GET	/api/wallets/user/:userId	List all wallets for a user
POST	/api/payment-intent	Create and authorize a payment intent

---

Request format

Every request to the Axis API must include a Content-Type: application/json header and a JSON body (for POST requests). Authenticated routes require one of two credentials:

• Authorization: Bearer <token> — a session token returned by POST /v1/auth/login, used with /v1/ routes and wallet management routes.
• x-api-key: <api-key> — a wallet-scoped API key (ax_live_ + 48 hex chars), used with POST /api/payment-intent.

const BASE_URL = "https://api.axispayments.ai";

async function axisRequest<T>(
  path: string,
  options: {
    method?: "GET" | "POST" | "PATCH" | "DELETE";
    body?: unknown;
    apiKey?: string;
    token?: string;
  } = {}
): Promise<T> {
  const { method = "GET", body, apiKey, token } = options;

  const headers: Record<string, string> = {
    "Content-Type": "application/json",
  };

  if (apiKey) {
    headers["x-api-key"] = apiKey;
  } else if (token) {
    headers["Authorization"] = `Bearer ${token}`;
  }

  const response = await fetch(`${BASE_URL}${path}`, {
    method,
    headers,
    body: body !== undefined ? JSON.stringify(body) : undefined,
  });

  if (!response.ok) {
    const error = await response.json();
    throw new AxisApiError(response.status, error);
  }

  return response.json() as Promise<T>;
}

---

Error response shape

When a request fails, Axis returns a JSON body with a consistent structure. status signals the failure, message gives a human-readable description, and the optional details object provides field-level validation errors — useful for surfacing inline form errors directly in your UI.

{
  "status": "fail",
  "message": "invalid request body",
  "details": {
    "amount": ["Must be greater than 0"]
  }
}

Field	Type	Always present	Description
status	string	✓	"fail" or "error" on failure responses
message	string	✓	Human-readable description of the failure
details	object	✗	Field-keyed validation errors (400 responses only)

Some error responses use success: false instead of status: "fail". Your error handler should treat both shapes as failure cases.

---

HTTP status codes

Status	Meaning	When you’ll see it
200	OK	Successful GET requests
201	Created	POST requests that create a new resource
400	Bad Request	Missing or invalid fields in the request body
401	Unauthorized	API key or session token is missing or invalid
402	Insufficient Funds	The wallet does not have enough balance to cover the payment
403	Forbidden	The authorization engine rejected the payment (see error codes below)
404	Not Found	The requested resource does not exist
500	Internal Server Error	Something went wrong on the Axis backend

---

Authorization error codes

When a payment intent is rejected with a 403, the response body includes a machine-readable code field from the authorization engine. Use this to give users and agents specific, actionable feedback rather than a generic error message.

Code	Meaning
MISSING_API_KEY	No x-api-key header was included in the request
INVALID_API_KEY	The provided API key does not match any active key
WALLET_INACTIVE	The wallet exists but has been deactivated
WALLET_EXPIRED	The wallet’s validity period has passed
SPEND_LIMIT_PER_TX_EXCEEDED	The payment amount exceeds the per-transaction spend limit
SPEND_LIMIT_PER_PERIOD_EXCEEDED	The payment would exceed the wallet’s rolling period spend limit
MERCHANT_NOT_ALLOWED	The destination merchant is not on the wallet’s allowlist
INSUFFICIENT_FUNDS	The wallet balance is too low to cover the payment amount

---

Handling errors in your frontend

The snippet below shows a complete error-handling wrapper built around the request helper defined earlier. AxisApiError preserves both the HTTP status and the parsed response body so you can branch on code for authorization failures and on details for validation failures.

// axis-error.ts

export interface AxisErrorBody {
  status: string;
  message: string;
  code?: AxisErrorCode;
  details?: Record<string, string[]>;
}

export type AxisErrorCode =
  | "MISSING_API_KEY"
  | "INVALID_API_KEY"
  | "WALLET_INACTIVE"
  | "WALLET_EXPIRED"
  | "SPEND_LIMIT_PER_TX_EXCEEDED"
  | "SPEND_LIMIT_PER_PERIOD_EXCEEDED"
  | "MERCHANT_NOT_ALLOWED"
  | "INSUFFICIENT_FUNDS";

export class AxisApiError extends Error {
  status: number;
  body: AxisErrorBody;

  constructor(status: number, body: AxisErrorBody) {
    super(body.message);
    this.name = "AxisApiError";
    this.status = status;
    this.body = body;
  }

  /** True when the authorization engine rejected the payment. */
  isAuthorizationFailure(): boolean {
    return this.status === 403;
  }

  /** True when request body validation failed — check `body.details` for field errors. */
  isValidationError(): boolean {
    return this.status === 400;
  }
}

// Usage example in a React component:
async function submitPayment(walletId: string, amount: number) {
  try {
    const result = await axisRequest("/api/payment-intent", {
      method: "POST",
      apiKey: process.env.NEXT_PUBLIC_AXIS_API_KEY,
      body: { walletId, amount },
    });
    return result;
  } catch (err) {
    if (err instanceof AxisApiError) {
      if (err.isAuthorizationFailure()) {
        switch (err.body.code) {
          case "INSUFFICIENT_FUNDS":
            showToast("Your wallet doesn't have enough funds for this payment.");
            break;
          case "SPEND_LIMIT_PER_TX_EXCEEDED":
            showToast("This payment exceeds the per-transaction spend limit.");
            break;
          case "MERCHANT_NOT_ALLOWED":
            showToast("This merchant is not permitted for your wallet.");
            break;
          case "WALLET_INACTIVE":
          case "WALLET_EXPIRED":
            showToast("Your wallet is no longer active. Please contact support.");
            break;
          default:
            showToast(`Payment declined: ${err.message}`);
        }
      } else if (err.isValidationError() && err.body.details) {
        // Surface field-level errors in a form
        setFieldErrors(err.body.details);
      } else if (err.status === 401) {
        redirectToLogin();
      } else {
        showToast("Something went wrong. Please try again.");
      }
    }
    throw err;
  }
}