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.
One key per action
Section titled “One key per action”- Generate a unique key before the first request and save it with your order.
- Send it in
Idempotency-Keywhen creating or changing a business resource. - After a timeout, retry the same method, path and body with that key.
- 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.
Read errors by code
Section titled “Read errors by code”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. |
Limits
Section titled “Limits”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 without duplicates
Section titled “Retry without duplicates”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_*.