Error handling and error codes

ArcenPay uses standard HTTP status codes for all REST responses and exposes a typed ArcenApiError class in the Node SDK so you can handle failure cases consistently in server-side code. Most integration errors fall into a small set of predictable categories: invalid credentials, missing resources, billing state conflicts, or on-chain failures.

HTTP status codes

Code	Meaning
`200`	Request succeeded.
`201`	Resource created.
`202`	Request accepted; an async recovery task is pending (e.g., subscription activated on-chain but ledger finalization queued).
`204`	No content (CORS preflight responses).
`400`	Malformed request body or missing required parameters.
`401`	Missing or invalid authentication credentials.
`403`	Authenticated but not entitled to the requested action (e.g., feature not included in the active plan).
`404`	The requested resource does not exist.
`409`	The request conflicts with current billing state (e.g., duplicate wallet, inactive plan, insufficient token allowance).
`425`	Too early — the on-chain transaction does not yet have enough confirmations.
`500`	Unexpected server-side failure.
`502`	On-chain transaction reverted.
`503`	A required server-side dependency is not configured (e.g., missing signer key).

Handling errors with `ArcenApiError`

The Node SDK throws ArcenApiError for any non-2xx response from the ArcenPay API. Catch it by checking instanceof ArcenApiError to access the structured fields:

import { ArcenClient, ArcenApiError } from "@arcenpay/node";

const client = new ArcenClient({
  apiKey: process.env.ARCENPAY_API_KEY!,
});

try {
  await client.activateSubscription({
    planId: "starter",
    paymentAccount: "0xabc...",
    company: { id: "company_123" },
  });
} catch (error) {
  if (error instanceof ArcenApiError) {
    console.error(error.statusCode, error.message);
  }
}

Property	Type	Description
`message`	string	Human-readable description of what went wrong.
`statusCode`	number	HTTP status code returned by the API.

Common error scenarios

Invalid or expired API key

Status: 401 Returned when the Authorization: Bearer header is missing, the key is not recognized, or the key has been revoked.

{ "error": "Missing API key. Provide Authorization: Bearer sk_/pk_/rk_…" }

{ "error": "Invalid API key" }

Verify that ARCENPAY_API_KEY is set in your environment and that the key has not been rotated or deleted in the dashboard. Check the endpoint auth matrix to confirm which key prefixes your endpoint accepts.

Company not found

Status: 404 Returned by GET /api/v1/companies/:id, PATCH /api/v1/companies/:id, and DELETE /api/v1/companies/:id when the supplied ID does not exist in your team.

{ "error": "Company not found" }

Feature not entitled (“Upgrade required”)

Status: 403 Returned by entitlement check endpoints when the company’s active plan does not include the requested feature, or when the company’s metered usage has been exceeded. Handle this in your application to show an upgrade prompt:

try {
  await client.consumeEntitlement({
    featureKey: "scan",
    company: { id: "company_123" },
    idempotencyKey: "scan-req-1",
  });
} catch (error) {
  if (error instanceof ArcenApiError && error.statusCode === 403) {
    // Show upgrade prompt to the user
  }
}

Invalid webhook signature

Status: 401 (returned by your own handler) When the HMAC signature on an incoming webhook does not match, you should reject the request. ArcenPay signs webhook payloads with x-arcenpay-signature: sha256=<hex>.

import { verifyWebhookSignature } from "@arcenpay/node";

const rawBody = await req.text();
const signatureHeader = req.headers.get("x-arcenpay-signature") ?? "";
const signature = signatureHeader.startsWith("sha256=")
  ? signatureHeader.slice("sha256=".length)
  : signatureHeader;

if (
  !verifyWebhookSignature(
    rawBody,
    signature,
    process.env.ARCENPAY_WEBHOOK_SECRET!,
  )
) {
  return new Response("Invalid signature", { status: 401 });
}

Always verify the raw request body before parsing it as JSON. Parsing first will invalidate the signature check.

Wallet rejected or on-chain failure

Status: 409 Returned by POST /api/v1/subscriptions/activate when the payment account does not have enough token balance or has not approved sufficient allowance for autopay to collect the first charge.

{
  "error": "The payment account does not have enough USDC for the first charge. Required: 49.00 USDC. Available: 10.00 USDC."
}

Other 409 causes at activation:

Condition	Error message
Insufficient token balance	`The payment account does not have enough <TOKEN> for the first charge.`
Insufficient token allowance	`The payment account has not approved enough <TOKEN> for autopay.`
Autopay not installed	`Autopay is not installed for this payment account yet.`
Plan already active	`This payment account already has an active subscription for on-chain plan <id>.`
Plan not published	`Published team plan not found for the supplied on-chain planId.`
Duplicate wallet	`This payment account is already linked to a different company in your workspace environment.`

Subscriptions API — subscription activation errors
Authentication — credential and auth errors
Webhooks — webhook signature verification

Get started

Credentials

Companies

Users

Events

Access control

Features

Subscriptions

Checkout sessions

Payment links

Invoices

Autonomous agents

Escrow

Mandates

Coupons

zkTLS proofs

Public specs

Error handling and error codes

HTTP status codes

Handling errors with `ArcenApiError`

Common error scenarios

Invalid or expired API key

Company not found

Feature not entitled (“Upgrade required”)

Invalid webhook signature

Wallet rejected or on-chain failure

​HTTP status codes

​Handling errors with ArcenApiError

​Common error scenarios

​Invalid or expired API key

​Company not found

​Feature not entitled (“Upgrade required”)

​Invalid webhook signature

​Wallet rejected or on-chain failure

​Related

HTTP status codes

Handling errors with `ArcenApiError`

Common error scenarios

Invalid or expired API key

Company not found

Feature not entitled (“Upgrade required”)

Invalid webhook signature

Wallet rejected or on-chain failure

Related