Erros

Formato de erro e todos os códigos que a API pode responder, com a mensagem em português pronta para o usuário.

Todo erro tem o mesmo formato:

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Saldo disponível insuficiente para esta operação (valor + tarifa, quando houver).",
    "details": { }
  },
  "requestId": "req_01JA..."
}

• code é estável: trate por ele no seu código.
• message é em português e pode ser mostrada a quem usa o seu sistema.
• details só aparece em alguns erros (ex.: fields na validação).
• requestId identifica a chamada; cite ao falar com o suporte.

Recurso que não é da sua conta responde 404, como se não existisse. 500 traz só uma mensagem genérica e já fica registrado para a equipe WyzeCash.

​

Gerais

HTTP	Código	Mensagem
401	INVALID_API_KEY	Chave de API inválida, revogada ou vencida.
403	FORBIDDEN	Você não tem permissão para isso. (a chave não tem o escopo)
403	IP_NOT_ALLOWED	Este IP não está liberado para esta chave de API.
403	TWO_FACTOR_NOT_ENABLED	Ative a autenticação em dois fatores (2FA) antes de movimentar dinheiro.
403	KYC_REQUIRED	Para sacar ou enviar Pix, envie seus documentos em Configurações › Verificação. Suas cobranças continuam funcionando normalmente.
404	NOT_FOUND	<Recurso> não encontrado.
422	VALIDATION	Dados inválidos. (details.fields lista os campos)
400	INVALID_BODY	Corpo da requisição inválido.
411	LENGTH_REQUIRED	Envie o cabeçalho Content-Length.
413	PAYLOAD_TOO_LARGE	O corpo da requisição passa do limite.
422	INSUFFICIENT_FUNDS	Saldo disponível insuficiente para esta operação (valor + tarifa, quando houver).
422	INVALID_AMOUNT	O campo precisa ser um valor em centavos maior que zero.
422	INVALID_PIX_KEY	Chave Pix inválida para o tipo informado.
400	IDEMPOTENCY_KEY_REQUIRED	Envie o cabeçalho Idempotency-Key (de 8 a 128 caracteres).
422	IDEMPOTENCY_KEY_REUSED	Essa Idempotency-Key já foi usada com outros dados.
409	IDEMPOTENCY_IN_PROGRESS	Já existe uma requisição com essa Idempotency-Key em andamento.
400	INVALID_CURSOR	Cursor de paginação inválido.
429	RATE_LIMITED	Muitas tentativas. Espere um pouco e tente de novo.
503	MAINTENANCE	A WyzeCash está em manutenção. Saques, Pix enviados, transferências e estornos voltam em instantes.
503	PIX_UNAVAILABLE	O Pix está indisponível no momento.
500	INTERNAL	Algo deu errado do nosso lado. Tente de novo.

​

Cobranças

HTTP	Código	Mensagem
422	BELOW_MINIMUM	O valor mínimo da cobrança é <valor>.
422	BELOW_PROVIDER_MINIMUM · ABOVE_PROVIDER_MAXIMUM	O valor mínimo (ou máximo) da cobrança é <valor>. · O valor mínimo no cartão é R$ 5,00. · O valor mínimo em cripto é R$ 2,00. (faixa aceita no momento)
422	METHOD_UNAVAILABLE	Pagamento no cartão indisponível no momento. · Pagamento em cripto indisponível no momento.
422	INVALID_CRYPTO_CURRENCY	Moeda não aceita.
422	VALIDATION	A moeda (cryptoCurrency) só vale para cobrança em cripto.
422	REFUND_NOT_AVAILABLE	Estorno só para cobranças pagas por Pix. Vendas no cartão e em cripto não têm estorno pela WyzeCash.
422	INVALID_EXPIRATION	A validade deve ser de 5 minutos a 30 dias.
422	INVALID_CUSTOMER	Cliente não encontrado.
404	NOT_FOUND	Cobrança não encontrada.

​

Links de pagamento

HTTP	Código	Mensagem
404	NOT_FOUND	Link de pagamento não encontrado.
422	LINK_UNAVAILABLE	Este link está pausado, vencido ou esgotado.
422	AMOUNT_NOT_ALLOWED	Escolha um dos valores sugeridos.
422	CUSTOMER_REQUIRED	Preencha seus dados para pagar.
422	METHODS_REQUIRED	Escolha pelo menos uma forma de pagamento.
422	METHOD_NOT_ALLOWED	Este link não aceita essa forma de pagamento. (página pública do link)

​

Saques

HTTP	Código	Mensagem
422	DESTINATION_REQUIRED	Informe a chave de destino (destination) ou o Pix Copia e Cola (copyPaste), só um deles. · Pela API, mande a chave Pix que vai receber em destination (ou o Pix Copia e Cola em copyPaste).
422	SUBACCOUNT_FUNDS	<valor> do seu saldo é das suas subcontas e não sai daqui. Você pode usar até <valor>.
422	INVALID_PIX_CODE	Não deu para ler a chave Pix deste código.
422	AMOUNT_MISMATCH	Este código é de <valor>; o valor não pode ser alterado.
422	BELOW_MINIMUM	O valor mínimo do saque é <valor>.
422	INTERNAL_ACCOUNT	Chaves de contas WyzeCash não são destino de saque. Use a transferência entre contas.
404	NOT_FOUND	Saque não encontrado.

​

Subcontas

HTTP	Código	Mensagem
422	INVALID_NAME	O nome precisa ter de 2 a 80 caracteres.
422	INVALID_EXTERNAL_ID	O externalId aceita letras, números, ponto, hífen e sublinhado (até 64) e não pode ter o formato de um ID de subconta.
422	INVALID_METADATA	O metadata precisa ser um objeto JSON. · O metadata pode ter até 2 KB.
409	EXTERNAL_ID_IN_USE	Já existe uma subconta com esse externalId.
404	NOT_FOUND	Subconta não encontrada.
404	DESTINATION_NOT_FOUND	Subconta de destino não encontrada.
422	SUBACCOUNT_INACTIVE	Esta subconta está desativada. · As duas subcontas precisam estar ativas.
422	SAME_SUBACCOUNT	Origem e destino precisam ser subcontas diferentes.
422	SUBACCOUNT_LOCKED	Esta subconta está com o saque (ou o recebimento) bloqueado. Com o bloqueio da WyzeCash: “A WyzeCash bloqueou a saída de dinheiro desta subconta. Fale com o suporte em Ajuda.”
422	INSUFFICIENT_SUBACCOUNT_BALANCE	A subconta tem só <valor>.
422	SUBACCOUNT_FUNDS	<valor> do seu saldo é das suas subcontas e não sai daqui. Você pode usar até <valor>. (no envio da principal)
422	INTERNAL_ACCOUNT	Chaves de contas WyzeCash não são destino de saque. Use a chave do cliente em outro banco.
422	DESTINATION_REQUIRED	Informe a chave Pix do cliente (destination) ou guarde uma na subconta.
422	FEE_ABOVE_AMOUNT	A taxa do saque é maior que o valor. Aumente o valor do saque.
409	SUBACCOUNT_BUSY	Essa subconta tem um saque em andamento. Espere concluir para excluir.
422	INVALID_SPLIT	Divida entre 1 e 10 subcontas. · A soma da divisão passa do valor da cobrança (<valor>). (na cobrança)
422	INVALID_PERIOD	Data inválida. Use AAAA-MM-DD ou data e hora ISO.
422	INVALID_KIND	Tipo inválido. Use: <tipos>.

​

Clientes

HTTP	Código	Mensagem
422	INVALID_NAME	Informe o nome do cliente.
422	INVALID_EMAIL	E-mail inválido.
422	INVALID_PHONE	Celular inválido. Use DDD + número.
422	INVALID_DOCUMENT	CPF ou CNPJ inválido.
404	NOT_FOUND	Cliente não encontrado.

​

Saldo, extrato, MED e tarifas

HTTP	Código	Mensagem
404	NOT_FOUND	Movimentação não encontrada. · Pedido de MED não encontrado. · Prova não encontrada.
422	INVALID_OPERATION	Operação desconhecida. (GET /v1/fees/preview)

<valor> é preenchido na hora, em reais (ex.: R$ 1.000,00).