Errors

ZeroClick returns errors on four surfaces: the REST API at https://api.zeroclick.io, the usage endpoints under /v1/usage, your own API (which returns three fixed bodies to ZeroClick), and the agent-facing pay URL (https://acme.pay.zeroclick.io). This page lists every machine code per surface.

The error envelope

Every error body is JSON with a machine code in error:

{ "error": "usage_exhausted" }

Some errors carry additional fields: pay URL errors may add a reason (and settlementReason), and amount_below_minimum adds minimumPurchaseUsd. Two cases fall outside the machine-code convention:

Request validation failures return 400 with a human-readable message in error describing the invalid field.
Server errors return 500 { "error": "Internal server error" }. The body never carries internals.

REST API errors

Management endpoints (sellers, services, meters, plans, prices, signing secrets, API keys, analytics) authenticate with Authorization: Bearer zc_… and share these codes:

Code	Status	Meaning
`missing_bearer_token`	401	The request has no `Authorization: Bearer` header.
`invalid_token`	401	The API key or session token did not verify.
`auth_type_not_allowed`	403	The endpoint does not accept this credential type. For example, API keys cannot manage API keys (session-only), and the usage endpoints accept API keys only.
`insufficient_scope`	403	The API key lacks a scope the endpoint requires. See keys and secrets.
`organization_required`	403	The caller has no current organization.
`organization_permission_required`	403	The caller may not act on the selected organization.
`seller_not_found`	404	No such seller in your organization.
`service_not_found`	404	No such service.
`meter_not_found`	404	No such meter.
`plan_not_found`	404	No such plan.
`plan_meter_price_not_found`	404	No such plan meter price.
`signing_secret_not_found`	404	No such signing secret.
`duplicate_slug`	409	A seller, service, or plan with this slug already exists in that scope.
`duplicate_key`	409	A meter with this key already exists on the service.
`duplicate_plan_meter_price`	409	The plan already prices this meter.
`payg_price_not_whole_cents`	422	Pay-as-you-go rates are charged per call, so `priceUsd` must be a whole-cent amount. Rates on credit and subscription plans keep full 6-decimal precision.

404 is the default for anything that does not resolve. A resource that exists but belongs to another organization is also a 404, never a 403.

Usage endpoint errors

Both usage endpoints live at https://api.zeroclick.io and require an API key: POST /v1/usage/check needs scope usage:read, POST /v1/usage needs usage:write. A wrong scope is 403 insufficient_scope; a non-API-key credential is 403 auth_type_not_allowed.

Allowance denials (`POST /v1/usage/check`)

A denial is not an HTTP error. The check returns 200 with the decision, and checking records nothing and burns no credit:

{ "allowed": false, "reason": "usage_exhausted" }

reason is null when allowed is true, and exactly one of these seven codes otherwise:

Reason	Meaning	Fix
`service_not_found`	No service with this slug under the organization your API key belongs to.	Send the service slug as configured in the dashboard, with a key from the owning organization.
`access_not_found`	The `zcRequestId` does not match a live ZeroClick request for this service, or the request has no purchase or payment behind it.	Pass the `zc-request-id` header value through unchanged. For unpaid traffic, this is the expected denial: return the `402 payment_required` body, and ZeroClick prices the challenge.
`access_inactive`	The buyer’s access is not active: canceled, or its period has not started.	Deny with the `402` body; the agent must purchase again.
`plan_expired`	The access period has ended.	Deny with the `402` body; the agent re-purchases.
`meter_not_found`	No meter with this slug exists on the service.	Use the meter key exactly as configured on the service.
`meter_not_priced`	The buyer’s plan does not price this meter. Also returned when an item declares neither `quantity` nor `maxQuantity` and the price has no `defaultMaxQuantity` to gate against.	Price the meter on the plan, or set the price’s `defaultMaxQuantity` (or declare an explicit `maxQuantity` per request).
`usage_exhausted`	The plan cannot cover this usage: credit or included allowance has run out.	Deny with the `402` body; ZeroClick challenges the agent to pay or top up.

See check allowances for the request shape and usage and allowances for how ZeroClick decides coverage.

Report errors (`POST /v1/usage`)

A replayed idempotencyKey is a success (200 with duplicate: true), not an error. Failures map to:

Status	Codes	Meaning
402	`access_inactive`, `plan_expired`, `usage_exhausted`	The access exists but can no longer be billed.
409	`meter_not_priced`	The buyer’s plan does not price this meter.
404	`service_not_found`, `access_not_found`, `meter_not_found`	The slug or agent does not resolve (the default for anything missing).

Errors your API returns to ZeroClick

Your API answers ZeroClick with exactly three non-2xx bodies. The seller SDKs build all of them; if you integrate over REST, return them byte-for-byte. An invalid, missing, or stale zc-signature, before any other work:

401

{ "error": "invalid_zeroclick_signature" }

A business denial (no allowance, unpaid probe). ZeroClick reads the usage list, prices it, and issues the buyer a payment challenge. The buyer never sees this body. planSlug is optional; usage: [] means an identity challenge for a free identity-scoped endpoint:

402

{
  "error": "payment_required",
  "serviceSlug": "product-watch",
  "usage": [{ "meterSlug": "requests", "quantity": 1 }]
}

The allowance API unreachable under a fail-closed outage policy:

503

{ "error": "allowance_unavailable" }

Errors agents see at your pay URL

Buyers transact at your pay URL (https://acme.pay.zeroclick.io). Once ZeroClick forwards a paid request, agents receive your API’s own status codes and bodies unchanged. The codes below are ZeroClick’s own, issued before or instead of the forward:

Code	Status	Meaning
`invalid_request`	400	Malformed purchase or top-up body.
`amount_required`	400	A credit plan purchase without `amountUsd`.
`payg_not_purchasable`	400	Purchase attempt on a pay-as-you-go plan: payg is called, never purchased.
`amount_not_cent_increment`	400	The `amountUsd` is not a whole-cent value; buyer-chosen amounts settle on-chain in whole cents.
`amount_below_minimum`	400	The `amountUsd` is under the plan’s minimum purchase; the body carries `minimumPurchaseUsd`.
`encryption_not_configured`	400	An `application/jose` body was sent but the seller publishes no encryption keys.
`invalid_compact_jwe`	400	The body is not a five-segment Compact JWE.
`unsupported_jwe_suite`	400	The JWE does not use the seller’s fixed `alg`/`enc` suite.
`jwe_kid_required`	400	The JWE protected header names no `kid`.
`unknown_jwe_kid`	400	The `kid` is not in the seller’s published JWKS.
`private_reply_jwk`	400	The reply JWK carries private key material.
`invalid_reply_jwk`	400	The reply JWK is not a public P-256 key.
`bearer_required`	401	The call needs a registered agent credential: buying or extending a plan, or a free-mode call covered by included units (the free case also requires the credential to be claimed by a human with a verified email). The body carries an `auth` block with the registration recipe. Pay-as-you-go per-call payments need no credential.
`payment_required`	402	The payment challenge: the one 402 an agent pays. A `reason` field distinguishes the cases below.
`seller_not_found`	404	The host does not map to a seller.
`plan_not_found`	404	Unknown plan id; agents use ids from `GET /manifest.json`.
`signing_secret_required`	409	The seller has no active signing secret: setup is incomplete.
`payment_request_mismatch`	409	The paid retry differs from the challenged request: method, path, or body bytes changed. The payment is bound to the request’s body digest, so the retry must be byte-identical.
`payment_request_already_completed`	409	A retry of a request that already delivered. Each payment forwards its request once.
`payment_request_in_flight`	409	A concurrent retry while another attempt for the same request is still running.
`payment_amount_mismatch`	409	A purchase or top-up retry carried a different `amountUsd` than the challenge that was paid.
`usage_not_priced`	409	The upstream’s refusal names usage no pay-as-you-go plan prices, so ZeroClick cannot mint a per-call challenge.
`entitlements_not_available`	501	This storefront does not sell plans or top-ups. Pay-as-you-go per call still works.
`capped_pricing_unavailable`	503	The request needs ceiling pricing but no reserve-and-pay-actual rail is currently available.

The seven 400 JWE codes apply only to requests sent with Content-Type: application/jose (end-to-end encrypted bodies). ZeroClick returns them before it asks for any payment.

A billing failure detected after your API already delivered a 2xx does not become an error status. ZeroClick returns the delivered response and surfaces the failure in the zc-usage-error response header. See headers.

`402 payment_required` reasons

Reason	Meaning
absent	The normal per-call charge: the body carries a `payment` block with the exact `amountUsd` and a signable challenge per protocol. The agent pays and retries.
`identity_invalid`	The identity proof did not verify. The agent signs a fresh challenge.
`access_not_found`	The agent has no active plan to draw from or extend. It purchases one first.
`usage_exhausted`	The plan’s credit ran out. The agent tops up or purchases again.
`settlement_failed`	The signed payment did not settle; `settlementReason` says why (for example `insufficient_funds`). The agent fixes its wallet and restarts for a fresh challenge.

A priced challenge looks like this (the same challenge also rides in the payment-required and www-authenticate response headers):

402

{
  "error": "payment_required",
  "zcAgentId": "agt_x7f2kq93bh0d",
  "zcRequestId": "zcreq_8h2m4x0q9k1f",
  "serviceSlug": "product-watch",
  "usage": [{ "meterSlug": "requests", "quantity": 1 }],
  "plan": { "id": "pln_...", "slug": "metered", "billingMode": "payg" },
  "payment": {
    "id": "apay_...",
    "amountUsd": "0.010000",
    "rail": "base_usdc",
    "network": "base"
  },
  "protocols": {
    "x402": {
      "x402Version": 2,
      "network": "eip155:8453",
      "scheme": "exact",
      "amount": "10000",
      "asset": "0x..."
    },
    "mpp": { "challengeId": "...", "method": "tempo", "intent": "charge" }
  }
}

The body also carries the standard x402 document fields (x402Version, resource, accepts) at the top level for body-reading clients. ZeroClick omits rail and network on anonymous challenges, where the agent picks a protocol by paying. The full lifecycle around this challenge is on how ZeroClick works; the protocols themselves are on payment protocols.

Get started

Concepts

Integrate your API

Your website

Resources

The error envelope

REST API errors

Usage endpoint errors

Allowance denials (`POST /v1/usage/check`)

Report errors (`POST /v1/usage`)

Errors your API returns to ZeroClick

Errors agents see at your pay URL

`402 payment_required` reasons

​The error envelope

​REST API errors

​Usage endpoint errors

​Allowance denials (POST /v1/usage/check)

​Report errors (POST /v1/usage)

​Errors your API returns to ZeroClick

​Errors agents see at your pay URL

​402 payment_required reasons

The error envelope

REST API errors

Usage endpoint errors

Allowance denials (`POST /v1/usage/check`)

Report errors (`POST /v1/usage`)

Errors your API returns to ZeroClick

Errors agents see at your pay URL

`402 payment_required` reasons