PayZu GatewayApoio

Erros


Nesta páginaFormato do corpoRespostas de qualquer rotaDecida pelo códigoRepita a cobrança e o estorno sem respostaCódigos mais comuns

Todo erro da API vem em JSON, com o status HTTP, o motivo e o request_id da chamada. Parte dos erros traz code; sem ele, decida por status_code.

Formato do corpo

json
{
  "status_code": 400,
  "error": "bad_request",
  "message": "A solicitação possui erros de validação.",
  "code": "PZ001",
  "request_id": "a1b2c3d4-0000-4000-8000-000000000000",
  "fields": [
    { "name": "amount", "message": "O valor mínimo é R$ 5,00." }
  ]
}
CampoTipoDescrição
status_codeintegerO mesmo status HTTP da resposta.
errorstringNome do status HTTP, em minúsculas, como bad_request ou not_found.
messagestringMotivo em português, para exibir ou registrar.
codestringCódigo estável do erro, com PZ e três dígitos. Só vem nos erros que têm código.
request_idstringIdentificador da chamada, o mesmo do cabeçalho X-Request-Id. Informe ao suporte para localizar a chamada.
fieldsarrayNos 400 de validação, os campos recusados, cada um com name e message.

Toda resposta da API traz o cabeçalho X-Request-Id, menos a resposta repetida pela Idempotency-Key. Na resposta repetida, o request_id do corpo é o da primeira chamada.

Respostas de qualquer rota

HTTPQuandoMensagem
400O corpo não é JSON válido, vem vazio com Content-Type: application/json ou traz um caractere nulo. Vem com o código de validação, sem fields.A solicitação possui erros de validação.
404O caminho não existe.Recurso não encontrado.
413O corpo JSON passa de 1 MB.O corpo da requisição passa do tamanho máximo aceito.
415O Content-Type não é aceito na rota, como multipart/form-data fora da defesa de contestação.Tipo de conteúdo não aceito nesta rota.

A proteção de borda responde um 403 em HTML, fora do formato de erro da API.

Ela recusa, antes da API, a chamada com conteúdo que trata como ataque, como javascript:alert(1) num campo de URL. Essa resposta vem sem X-Request-Id.

Decida pelo código

RespostaComo decidir
Com codePelo code, que não muda de sentido. A mensagem pode mudar, e o mesmo código pode ter mais de uma, como o da URL do webhook, com uma para cada regra.
Sem codePelo status_code, com a message. É o caso do 404 de recurso que não existe e das recusas de regra sem código próprio. Essas mensagens estão em Sem código.
400 de validaçãoPor fields, quando vem, com uma entrada por campo recusado. Sem fields, a recusa é do corpo inteiro, como em Respostas de qualquer rota.
Cartão recusadoNão é erro: a resposta é 201, com a tentativa failed em payments[0], ou em invoice.payments[0] na criação da assinatura, o motivo em failure.code, de PZ220 a PZ298, e a frase para o cliente em failure.message. Veja Vender no cartão.
429Espere um minuto antes de repetir. Só vem em POST /v1/card-tokens e nas rotas do checkout, contado por IP. Veja Limites de requisição.
5xxGuarde o request_id.
  • Um 404 sem código diz que o recurso não existe na sua conta: o id de outra conta também responde 404.
  • Em fields, name traz o caminho do campo, como items[0].unit_price, e vem unknown quando a regra não aponta um campo. Nas regras de tipo e de tamanho, message vem em inglês, como Required.

O 503 com código pode ser repetido depois de um intervalo.

Ele sai quando o processamento do cartão, a alteração do valor da assinatura ou a reativação da assinatura estão indisponíveis. Se mandou Idempotency-Key na alteração ou na reativação, repita com uma chave nova: a mesma chave recebe o 503 guardado por 24 horas, com Idempotent-Replayed: true.

Repita a cobrança e o estorno sem resposta

Quando a criação ou o pagamento de uma fatura, a criação de uma assinatura ou um estorno fica sem resposta, repita com a mesma Idempotency-Key. A PayZu retorna a resposta guardada, com Idempotent-Replayed: true, em vez de cobrar de novo. Veja Idempotência.

RespostaFica guardadaNova tentativa
Erro antes de a cobrança ou o estorno sair para a adquirente, como um 404 ou PZ201NãoCorrija a chamada e repita com a mesma chave.
Resposta depois do envio, como o 201 com o cartão recusado, PZ403 ou PZ404SimUse outra chave, como em Quando o estorno não sai.

Códigos mais comuns

CódigoHTTPMensagem
PZ001400A solicitação possui erros de validação.
PZ010400Envie o cabeçalho Idempotency-Key nesta operação.
PZ201400Token de cartão inválido ou vencido. Gere o token de novo.
PZ750400URL inválida.
A URL não pode ter usuário ou senha.
A URL precisa usar https.
A URL precisa usar a porta 443.
A URL aponta para um endereço interno.
A URL aponta para um serviço interno do Google Cloud. Use um domínio próprio.
A URL resolve para um endereço interno.
PZ020401Chave de API ausente.
PZ021401Chave de API inválida.
PZ030403Gateway suspenso para esta conta. Fale com o suporte PayZu.
PZ031403Esta conta só tem acesso de consulta.
PZ032403Cartão não habilitado para esta conta. Fale com o suporte para habilitar ou ofereça apenas Pix.
PZ033403Pix não habilitado para esta conta. Fale com o suporte para habilitar.
PZ034404Recorrência não ativada para esta conta.
PZ011409Idempotency-Key já usada com outra requisição.
PZ012409Requisição com esta Idempotency-Key ainda está em processamento.
PZ113409Esta fatura tem um pagamento aguardando confirmação. Tente novamente mais tarde.
PZ400409Só uma fatura paga pode ser estornada.
PZ101422Valor fora do limite desta conta.
PZ202503Não foi possível processar o cartão agora. Tente de novo.
CódigosOnde valem
PZ020, PZ021 e PZ030Em toda rota que usa a chave de API. Veja Autenticação.
PZ034Nas rotas de planos, assinaturas e configurações. Veja Recorrência.

Todos os códigos do PayZu Gateway estão no Catálogo de erros.