Começando

Erros

A API usa os status HTTP convencionais e sempre retorna um envelope de erro padronizado, com um código estável para tratamento programático e uma mensagem legível em português.

Envelope de erro

Campo	Tipo	Obrigatório	Descrição
`error`	object	Sim	Presente em todas as respostas de erro.
`error.code`	string	Sim	Código estável em snake_case. Use-o na sua lógica.
`error.message`	string	Sim	Descrição legível (pt-BR). Pode mudar; não faça parse.
`error.details`	array \| object	Não	Informações extras. Em `validation_error` é uma lista `[{ field, message }]`; em `duplicate_external_id` traz `transaction_id`.

Status HTTP

Status	Significado
200 / 201	Sucesso. 201 indica recurso criado.
400	Requisição malformada (JSON inválido, credenciais ausentes).
401	Autenticação ausente, inválida ou expirada.
403	Sem permissão: conta bloqueada ou em análise, saques bloqueados, 2FA inativo ou IP não autorizado.
404	Recurso não encontrado.
409	Conflito: external_id duplicado.
413	Corpo da requisição maior que 64 KB.
422	Parâmetros válidos em formato, mas recusados pela regra de negócio ou validação.
429	Limite de requisições excedido.
500	Erro interno. Pode ser retentado com segurança se você usar external_id.
502	Instituição parceira indisponível no momento. Tente novamente em instantes com o mesmo external_id.

Códigos de erro

Código	HTTP	Descrição
`invalid_json`	400	O corpo não é um JSON válido.
`invalid_request`	400	Faltam client_id e/ou client_secret na emissão de token.
`unauthorized`	401	Header Authorization: Bearer ausente.
`invalid_token`	401	Token inválido, expirado ou credencial revogada.
`invalid_client`	401	client_id/client_secret incorretos ou revogados.
`account_pending`	403	Conta em análise — operações financeiras ficam bloqueadas até a aprovação.
`account_blocked`	403	Conta bloqueada. Fale com o suporte.
`kyc_required`	403	Verificação de identidade (KYC) não aprovada: sem cobranças, saques, links ou API até a aprovação. Envie os documentos no painel.
`two_factor_required`	403	Saque solicitado por conta sem verificação em duas etapas (2FA) ativa.
`cashout_disabled`	403	Saques bloqueados para a conta. Fale com o suporte.
`ip_not_allowed`	403	IP de origem não está na allowlist da credencial.
`not_found`	404	Transação não encontrada (ou de outra conta).
`duplicate_external_id`	409	Já existe transação com este external_id.
`payload_too_large`	413	Corpo maior que 64 KB.
`validation_error`	422	Um ou mais campos inválidos — veja details.
`amount_too_low`	422	Valor abaixo do mínimo ou insuficiente para cobrir as taxas.
`amount_too_high`	422	Valor acima do máximo permitido para uma cobrança PIX.
`insufficient_balance`	422	Saldo disponível insuficiente para o saque (valor + taxa).
`invalid_pix_key`	422	Chave PIX inválida para o tipo informado.
`method_unavailable`	422	Meio de pagamento indisponível em um link de pagamento. Use `["pix"]`.
`rate_limited`	429	Limite de requisições excedido.
`internal_error`	500	Erro inesperado no servidor.
`provider_unavailable`	502	Não foi possível gerar o PIX na instituição parceira agora. Tente novamente.

Exemplos de erro

{
  "error": {
    "code": "validation_error",
    "message": "Parâmetros inválidos",
    "details": [
      {
        "field": "amount",
        "message": "no máximo 2 casas decimais"
      }
    ]
  }
}