Erros

Os erros usam códigos de status HTTP convencionais e um único envelope JSON:

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_invalid",
    "message": "amount must be a positive decimal string like \"59.90\"",
    "param": "amount",
    "request_id": "req_01J…"
  }
}

• type é uma categoria estável (veja abaixo). Faça o seu código decidir com base nele.
• code é um motivo mais específico, legível por máquina. Novos códigos podem ser adicionados; trate códigos desconhecidos pelo seu type.
• param indica o campo com problema, quando houver um.
• message é para pessoas e pode mudar — não o interprete no código.
• request_id corresponde ao cabeçalho de resposta Request-Id.

Tipos de erro

type	Status típico	Significado	O que fazer
invalid_request_error	400, 422	JSON malformado, campo desconhecido, valor inválido	Corrija a requisição; não repita sem mudanças
authentication_error	401	Credenciais ausentes, inválidas ou revogadas	Verifique a chave e o ambiente
permission_error	403	Autenticado, mas sem permissão (escopo, função, restrição de loja)	Use uma chave com o escopo correto
not_found_error	404	O objeto não existe ou não é visível para a sua organização	Verifique o id e o ambiente
conflict_error	409	O estado do objeto não permite a ação (por exemplo, cancelar depois que uma transferência foi observada)	Releia o objeto e decida
idempotency_error	409, 422	Idempotency-Key reutilizada com parâmetros diferentes	Use uma nova chave para uma nova operação
rate_limit_error	429	Requisições demais; veja Retry-After	Espere e tente de novo
feature_unavailable_error	403	O recurso ainda não está disponível para a sua conta: conta ainda não ativada, saques não ativados, rede desabilitada ou parceiro fiduciário não contratado	Não repita; o recurso não está habilitado para a sua conta
api_error	500	Erro inesperado do servidor (registrado com o request id)	Tente de novo com backoff usando a mesma Idempotency-Key

Campos desconhecidos no corpo das requisições são recusados com invalid_request_error / parameter_unknown em vez de ignorados em silêncio, para que erros de digitação apareçam imediatamente.

Conta ainda não ativada

Os pagamentos são ativados após a verificação e aprovação da sua conta. Enquanto a sua conta não estiver ativada, estes códigos são esperados:

code	type	Quando
live_keys_disabled	feature_unavailable_error	Conta ainda não ativada: criar uma chave de API live antes de a sua conta ser ativada
live_mode_disabled	feature_unavailable_error	Conta ainda não ativada: usar o modo live, com uma chave de API live ou no painel, enquanto a sua conta não estiver ativada
live_processing_unavailable	feature_unavailable_error	Conta ainda não ativada para pagamentos: criar uma intenção de pagamento antes de o processamento de pagamentos live ser ativado para a sua conta
payouts_unavailable	feature_unavailable_error	Conta ainda não ativada para saques: solicitar um saque antes de os saques serem ativados para a sua conta (eles são ativados separadamente dos pagamentos live)
payouts_live_only	invalid_request_error (422)	Gerenciar endereços de saque ou saques fora do modo live — saques movimentam fundos reais
test_mode_disabled	feature_unavailable_error	Criar ou usar uma chave que não é live, ou criar um pagamento que não é live. Toda chave e todo pagamento são live: crie uma chave de API live quando a sua conta for ativada

Nenhum deles é resolvido com novas tentativas. Quando a sua conta é ativada, o checklist de configuração no painel marca a etapa do modo live como concluída.

Requisições entre tenants

Requisições a objetos de outra organização retornam not_found_error, não permission_error. Isso evita confirmar que um id existe.

Classes de erro dos SDKs

SDK	Classe base	Classes específicas
TypeScript	FeitPayError	FeitPayInvalidRequestError, FeitPayAuthenticationError, FeitPayPermissionError, FeitPayNotFoundError, FeitPayConflictError, FeitPayIdempotencyError, FeitPayRateLimitError, FeitPayFeatureUnavailableError, FeitPayAPIError, FeitPayConnectionError
Python	FeitPayError	InvalidRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, IdempotencyError, RateLimitError, FeatureUnavailableError, APIError, APIConnectionError
Go	*feitpay.Error	consulte Type, Code, Param, Status, RequestID (ou feitpay.ErrorType(err))

Erros de conexão (connection_error, status 0) significam que nenhuma resposta foi recebida; repetir com a mesma Idempotency-Key é seguro.