Pular para o conteúdo

Idempotência, erros e limites

Se uma requisição expira, você não sabe se ela teve sucesso. Repita a mesma operação com a mesma Idempotency-Key para evitar criar um segundo pagamento.

  1. Gere uma chave única antes da primeira requisição e salve-a com o seu pedido.
  2. Envie-a em Idempotency-Key ao criar ou alterar um recurso de negócio.
  3. Após um timeout, repita o mesmo método, caminho e corpo com essa chave.
  4. Para uma nova ação, crie uma nova chave.

A chave deve ter conteúdo e no máximo 128 bytes. Repetir uma ação concluída retorna sua resposta salva. Alterar o corpo sob a mesma chave retorna 409 idempotency_conflict.

Isso se aplica a mutações de negócio como faturas, lojas, chaves e webhooks. Chamadas GET somente leitura e desafios de entrada não usam esse mecanismo. Siga os requisitos de cada endpoint.

external_id ajuda a associar um pagamento ao seu pedido; não é uma chave de idempotência.

Exemplo:

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

Use error.code no seu programa. Não presuma sucesso a partir do corpo da resposta sem antes verificar o status HTTP.

Código Próxima ação
unauthorized Verifique a credencial, as permissões e qualquer restrição de IP. Entre novamente se a sessão expirou.
mfa_required Complete o segundo fator da conta usando sua sessão.
onboarding_required Complete /onboarding antes de operações de loja.
idempotency_key_required Forneça uma chave salva não vazia, com no máximo 128 bytes.
idempotency_conflict Encontre a requisição original. Não crie um novo pagamento silenciosamente.
json_content_type_required / invalid_json Envie Content-Type: application/json e apenas campos documentados.
unsupported_network / unsupported_asset Selecione uma rede e um token compatíveis.
network_not_ready / asset_not_ready Aguarde a disponibilidade ou selecione outra rota pronta.
address_unavailable 503: não foi possível gerar o endereço agora. Repita a mesma requisição com a mesma Idempotency-Key.
amount_below_minimum / fee_exceeds_amount Verifique o valor, as casas decimais e as condições da loja.
shop_archived / shop_not_found Verifique a loja e o acesso.
invalid_expires_in Envie 1h, 2h, 1d, 7d, 30d, 180d ou 365d, e apenas ao criar uma fatura. Depósitos não expiram.
invalid_assets / issuance_in_group Envie pares distintos de {chain_id, token} sem chain_id e token; cancele ou pause um grupo pelo próprio id. Veja vários tokens ou redes.
solana_setup_required / tron_setup_required Defina primeiro o destinatário Solana ou Tron da loja.
invoice_amount_limit / sandbox_amount_limit Reduza o valor para dentro do limite.
active_invoice_limit_reached / deposit_address_limit_reached Cancele faturas ou desative depósitos que você não precisa mais, ou peça ao Invoise para aumentar o limite.
api_key_limit_reached / too_many_allowed_ips / webhook_limit_reached Revogue chaves não usadas, reduza a lista de IPs ou reutilize um endpoint existente.
team_limit_reached Remova um membro ou revogue um convite pendente, ou peça ao Invoise para aumentar o limite.
shop_limit_reached Arquive uma loja que você não usa mais, ou peça ao Invoise para aumentar o limite.
own_merchant / last_merchant_owner / wallet_in_use Você não pode sair do lojista que criou nem sendo o último proprietário dele; primeiro tire da sua carteira os repasses das lojas listadas.
account_disabled A equipe do Invoise bloqueou a conta; o motivo está em error.details. Veja contas bloqueadas.
rate_limited Aguarde o número de segundos em Retry-After antes de repetir.

Quando uma requisição excederia um limite, o Invoise a rejeita com o corpo de erro usual e o código abaixo.

Limite Valor Erro
Valor de uma fatura 1.000.000 tokens por padrão 400 invoice_amount_limit
Valor de uma fatura sandbox ou transferência simulada 10.000 tokens 400 sandbox_amount_limit
Faturas ativas por lojista 2.000 400 active_invoice_limit_reached
Endereços de depósito ativos por lojista, por família de rede EVM 100.000, Tron 100.000, Solana 100 400 deposit_address_limit_reached
Novos endereços de pagamento por lojista por hora: faturas, depósitos e cada uma das suas opções o limite de faturas ativas do lojista, 2.000 por padrão 429 rate_limited
Lojas ativas por lojista 10 400 shop_limit_reached
Chaves de API por loja que não estejam revogadas 10 400 api_key_limit_reached
Endereços IP ou faixas CIDR permitidos por chave 10 400 too_many_allowed_ips
Endpoints de webhook por loja 10 400 webhook_limit_reached
Membros da equipe e convites pendentes por lojista 10 400 team_limit_reached
Requisições por minuto 1.200 por credencial, das quais no máximo 120 não são GET; 3.000 e 300 por IP do cliente 429 rate_limited

Os limites de valor estão em tokens inteiros, não em unidades base. Todo token compatível é uma stablecoin em dólar, então 1.000.000 tokens equivale a cerca de $1.000.000.

Uma fatura fica ativa até ser paga, cancelada ou expirar. Uma fatura oferecida em várias redes conta uma única vez. Um endereço de depósito fica ativo até ser desativado; cada opção de rede de um depósito é um endereço separado. Sandbox e produção são contados separadamente para os dois limites. Uma loja arquivada não conta para o limite de lojas.

Os valores acima são os padrões. A equipe do Invoise pode definir para um lojista outros limites de fatura, endereço de depósito, loja e equipe, então os seus podem ser diferentes, e alterar o valor máximo de fatura para todos os lojistas.

O limite de equipe se aplica tanto ao convidar quanto ao aceitar um convite. A URL de um endpoint de webhook pode ser alterada, então você pode reutilizar um endpoint em vez de adicionar outro.

As requisições são contadas por chave de API ou sessão do painel e sempre também por IP do cliente, então uma credencial inventada não começa uma contagem nova.

Toda resposta 429 traz Retry-After, o número de segundos a esperar. Para o limite de requisições por minuto, é 60. Limites por hora, como o orçamento de endereços novos, os códigos de entrada por e-mail e os desafios de carteira, informam os segundos até a janela reabrir, até uma hora.

Repita timeouts e erros temporários do servidor com a mesma chave, usando atrasos crescentes. Em 429, aguarde os segundos em Retry-After (até uma hora para o orçamento de endereços novos); não envie mais requisições imediatamente. Corrija entradas inválidas e erros de acesso antes de repetir.

Para webhooks, o Invoise repete a entrega por até 72 horas; veja Repetições. Aceite o evento de forma durável, retorne 2xx e depois processe-o. Deduplique por Invoise-Event-ID.

As rotas antigas /projects são aliases de /shops, incluindo seu escopo de idempotência. Use /shops para novas integrações. Nomes de erro legados podem usar project_*.