Recusas

{
  "code": "insufficient_balance",
  "error": "Not enough funds",
  "request_id": "9f3c1e2a7b4d5e60"
}

Tome decisões com base em code. Algumas recusas trazem campos adicionais:

{
  "code": "invalid_targeting",
  "error": "Unknown city",
  "field": "city",
  "value": "nosuchcity"
}
{
  "code": "unsupported_field",
  "error": "Field is not supported here",
  "field": "count"
}
{
  "code": "rate_limited",
  "error": "Too many requests",
  "retry_after": 12,
  "limit": 120
}

O 404 em GET /api/v1/orders/{id} traz só error e request_id, sem code.

Catálogo de códigos

Código	Status	Quando
invalid_api_key	401	a chave não foi aceita
validation_failed	400	uma restrição de campo foi violada
invalid_body	400	corpo ou campo com formato errado
unknown_product	400	slug desconhecido ou produto fora de venda
insufficient_scope	403	a chave não tem a permissão exigida pela rota
not_found	404	o recurso não existe ou pertence a outra conta
idempotency_in_progress	409	a requisição anterior com esta chave ainda está em execução
replace_in_progress	409	a substituição dos endereços do pacote já está em andamento
invalid_volume	422	volume fora do intervalo do produto
invalid_quantity	422	mais endereços do que é possível comprar em uma compra
country_unavailable	422	o país não está à venda para este produto
unknown_plan, unknown_operator, unknown_period	422	o país escolhido não tem esse plano, local ou período - confira os parâmetros
out_of_stock	422	o local tem menos endereços livres do que o pedido
unsupported_capability	422	a operação não se aplica ao tipo deste pacote
package_expired	422	o período do pacote de endereços terminou - prolongue primeiro
prolong_window_closed	422	não é mais possível recuperar os endereços com prolongamento - é preciso uma nova compra
type_unavailable	422	a configuração não pode ser cotada nem vendida
insufficient_balance	422	saldo insuficiente
unsupported_field	422	chave não aplicável no corpo; vem com field
invalid_targeting	422	o valor não está no catálogo geográfico; vem com field e value
package_unavailable	422	a operação não é possível no estado atual do pacote ou com essas configurações
purchase_refunded	422	a compra não foi concluída, o dinheiro foi devolvido
idempotency_key_required	422	falta o cabeçalho Idempotency-Key
idempotency_key_invalid	422	o cabeçalho está vazio ou tem mais de 255 caracteres
idempotency_key_reused	422	a mesma chave com outro corpo
rate_limited	429	a cota da chave se esgotou
replace_cooldown	429	os endereços foram substituídos recentemente; quando será possível de novo está em replace_available_at
order_failed	500	o pedido não foi feito, o saldo não foi debitado
package_failed	500	a operação no pacote falhou, o dinheiro não foi debitado
order_needs_attention	500	dinheiro debitado, a entrega não ocorreu, análise manual
operation_indeterminate	500	repetição com a chave de uma operação cujo resultado não está definido
catalog_unavailable	503	o catálogo geográfico do produto ainda não foi sincronizado

Operações pagas

Código	Dinheiro	Ação
order_failed, package_failed	não debitado	repetir com o mesmo Idempotency-Key
purchase_refunded (422)	devolvido	repetir como uma nova compra com uma nova chave
order_needs_attention	debitado, resultado em apuração	não repetir, fale com o suporte informando o order_id
operation_indeterminate	resultado não definido	não repetir com a mesma chave; confira pedidos e pacotes e depois fale com o suporte

A mensagem em 5xx é neutra - decida com base em code.

Suporte: @ipvrent_support, [email protected]. Anexe o request_id do corpo da recusa e o order_id, se houver.

Novas tentativas

Timeout não é recusa: a requisição pode ter chegado. Repetir com o mesmo Idempotency-Key retorna a mesma resposta. Em 409 idempotency_in_progress, aguarde e repita com a mesma chave.

Não devem ser repetidos: insufficient_balance, invalid_volume, invalid_quantity, unknown_product, unsupported_field, unsupported_capability, invalid_targeting, prolong_window_closed. Em rate_limited, aguarde Retry-After; em replace_cooldown, aguarde replace_available_at.