Códigos de erro

Todos os erros da API devolvem o mesmo envelope:

{
  "error": {
    "code": "payment_rejected",
    "message": "The selected currency is invalid.",
    "documentation_url": "https://app.so-amtar.com/docs/errors#payment_rejected"
  }
}

Código HTTP	Significado
400	Pedido mal formado (cabeçalho inválido, JSON inválido)
401	Autenticação (chave ausente, inválida ou revogada)
403	Autorização (permissão insuficiente)
404	Recurso não encontrado para este comerciante
409	Conflito (idempotência incoerente, pedido em curso)
422	Validação de negócio (limite excedido, estado incoerente)
429	Limite de pedidos
500	Erro interno (avise o suporte)
502	Orange Money indisponível

Lista completa

Autenticação

• missing_credentials — cabeçalho Authorization ausente
• invalid_api_key — chave desconhecida, revogada ou expirada, ou IP fora da lista autorizada
• scope_insufficient — a chave não tem a permissão exigida por esta rota

Idempotência

• idempotency_key_too_long — mais de 255 caracteres
• idempotency_conflict — mesma chave com um corpo diferente, OU pedido ainda em curso

Pagamentos

• payment_rejected — validação de negócio (fornecedor, moeda, precisão do montante, limite, KYC)
• gateway_error — o Orange Money recusou iniciar o pagamento (502)
• transaction_not_found — id ou referência desconhecidos para este comerciante (ou criados no outro modo)

Reembolsos (POST/v1/refunds, scope can_refund)

• transaction_not_found (404) — transação desconhecida para este comerciante
• refunds_disabled (422) — os reembolsos não estão ativados para a sua conta
• refund_environment_mismatch (422) — chave de teste sobre uma transação live ou vice-versa
• transaction_not_refundable (422) — o estado da transação não é success
• non_payment_transaction_refund (422) — só os pagamentos são reembolsáveis (não os pagamentos de saída)
• provider_refund_unsupported (422) — o fornecedor não suporta reembolsos
• refund_payer_phone_missing (422) — o pagamento não tem número do pagador a creditar
• amount_must_be_positive (422) — amount deve ser superior a zero
• transaction_already_fully_refunded (422) — o pagamento já está totalmente reembolsado
• refund_exceeds_refundable (422) — amount excede o montante restante reembolsável
• refund_rejected (422) — reembolso recusado por outro motivo de negócio
• scope_insufficient (403) — a chave não tem o scope can_refund
• refund_not_found (404) — GET/v1/refunds/{id}: id ou referência desconhecidos

Pagamentos de saída (payouts)

• payout_not_allowed_in_test_mode — os pagamentos de saída exigem uma chave live (sk_live_…)

Pagamentos divididos (splits)

• split_rejected — total superior ao montante da transação, beneficiário inativo ou transação já finalizada

O que fazer

Código	Ação recomendada
4xx (validação)	Corrigir o pedido e usar uma nova Idempotency-Key
401	Verificar a chave. Não repetir.
409	Rever a sua lógica de idempotência
429	Aguardar o Retry-After e repetir
5xx	Repetir com a mesma Idempotency-Key, com espera exponencial
502	Orange Money indisponível: repetir após alguns segundos

Comunicar um erro

Escreva para support@so-amtar.com indicando:

• o código de erro
• o documentation_url
• a data e hora exatas (UTC)
• o seu merchant_ref ou o id SOAMTAR
• o cabeçalho X-Request-Id da resposta (se existir)