Skip to content

Idempotency, errors and limits

If a request times out, you do not know whether it succeeded. Retry the same operation with the same Idempotency-Key to avoid creating a second payment.

  1. Generate a unique key before the first request and save it with your order.
  2. Send it in Idempotency-Key when creating or changing a business resource.
  3. After a timeout, retry the same method, path and body with that key.
  4. For a new action, create a new key.

The key must be non-empty and no longer than 128 bytes. Repeating a completed action returns its stored response. Changing the body under the same key returns 409 idempotency_conflict.

This applies to business mutations such as invoices, shops, keys and webhooks. Read-only GET calls and sign-in challenges do not use this mechanism. Follow each endpoint’s requirements.

external_id helps associate a payment with your order; it is not an idempotency key.

Example:

{"error":{"code":"idempotency_conflict","message":"idempotency_conflict"}}

Use error.code in your program. Do not infer success from the response body without first checking the HTTP status.

Code Next action
unauthorized Check the credential, permissions and any IP restriction. Sign in again if the session expired.
mfa_required Complete the account’s second factor using its session.
onboarding_required Complete /onboarding before shop operations.
idempotency_key_required Supply a saved non-empty key, at most 128 bytes.
idempotency_conflict Find the original request. Do not silently create a new payment.
json_content_type_required / invalid_json Send Content-Type: application/json and only documented fields.
unsupported_network / unsupported_asset Select a supported network and token.
network_not_ready / asset_not_ready Wait for availability or select another ready route.
address_unavailable 503: the address could not be derived right now. Retry the same request with the same Idempotency-Key.
amount_below_minimum / fee_exceeds_amount Check the amount, decimals and shop terms.
shop_archived / shop_not_found Check the shop and access.
invalid_expires_in Send 1h, 2h, 1d, 7d, 30d, 180d or 365d, and only when creating an invoice. Deposits do not expire.
invalid_assets / issuance_in_group Send distinct {chain_id, token} pairs without chain_id and token; cancel or pause a group by its own id. See several tokens or networks.
solana_setup_required / tron_setup_required Set the shop’s Solana or Tron recipient first.
invoice_amount_limit / sandbox_amount_limit Lower the amount to within the limit.
active_invoice_limit_reached / deposit_address_limit_reached Cancel invoices or disable deposits you no longer need, or ask Invoise to raise the limit.
api_key_limit_reached / too_many_allowed_ips / webhook_limit_reached Revoke unused keys, shorten the IP list or reuse an existing endpoint.
team_limit_reached Remove a member or revoke a pending invitation, or ask Invoise to raise the limit.
shop_limit_reached Archive a shop you no longer use, or ask Invoise to raise the limit.
own_merchant / last_merchant_owner / wallet_in_use You cannot leave the merchant you created or as its last owner; move the listed shops’ payouts off your wallet first.
account_disabled Invoise staff blocked the account; the reason is in error.details. See blocked accounts.
rate_limited Wait for the number of seconds in Retry-After before retrying.

When a request would exceed a limit, Invoise rejects it with the usual error body and the code below.

Limit Value Error
Amount of one invoice 1,000,000 tokens by default 400 invoice_amount_limit
Amount of one sandbox invoice or simulated transfer 10,000 tokens 400 sandbox_amount_limit
Active invoices per merchant 2,000 400 active_invoice_limit_reached
Active deposit addresses per merchant, per network family EVM 100,000, Tron 100,000, Solana 100 400 deposit_address_limit_reached
New payment addresses per merchant per hour: invoices, deposits and each of their options the merchant’s active invoice limit, 2,000 by default 429 rate_limited
Active shops per merchant 10 400 shop_limit_reached
API keys per shop that are not revoked 10 400 api_key_limit_reached
Allowed IP addresses or CIDR ranges per key 10 400 too_many_allowed_ips
Webhook endpoints per shop 10 400 webhook_limit_reached
Team members and pending invitations per merchant 10 400 team_limit_reached
Requests per minute 1,200 per credential, of which at most 120 are not GET; 3,000 and 300 per client IP 429 rate_limited

Amount limits are in whole tokens, not base units. Every supported token is a dollar stablecoin, so 1,000,000 tokens is about $1,000,000.

An invoice is active until it is paid, cancelled or expired. An invoice offered on several networks counts once. A deposit address is active until it is disabled; each network option of a deposit is a separate address. Sandbox and production are counted separately for both limits. An archived shop does not count toward the shop limit.

The values above are the defaults. Invoise staff can set different invoice, deposit address, shop and team limits for a merchant, so yours may differ, and can change the amount cap for every merchant.

The team limit applies both when inviting and when accepting an invitation. A webhook endpoint’s URL can be changed, so you can reuse an endpoint instead of adding one.

Requests are counted per API key or dashboard session, and always per client IP as well, so an invented credential does not start a fresh count.

Every 429 response carries Retry-After, the number of seconds to wait. For the per-minute request limit it is 60. Hourly limits, such as the new-address budget, sign-in email codes and wallet challenges, give the seconds until their window reopens, which can be up to an hour.

Retry timeouts and temporary server errors with the same key, using increasing delays. On 429, wait the number of seconds in Retry-After (up to an hour for the new-address budget); do not send more requests immediately. Fix invalid input and access errors before retrying.

For webhooks, Invoise retries delivery for up to 72 hours; see Retries. Accept the event durably, return 2xx, then process it. Deduplicate by Invoise-Event-ID.

Older /projects routes are aliases of /shops, including their idempotency scope. Use /shops for new integrations. Legacy error names may use project_*.