Erros
Nesta página
Formato do corpoRespostas de qualquer rotaDecida pelo códigoRepita a cobrança e o estorno sem respostaCódigos mais comunsTodo 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
{
"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." }
]
}{
"status_code": 409,
"error": "conflict",
"message": "Esta fatura tem um pagamento aguardando confirmação. Tente novamente mais tarde.",
"code": "PZ113",
"request_id": "a1b2c3d4-0000-4000-8000-000000000000"
}{
"status_code": 404,
"error": "not_found",
"message": "Fatura não encontrada para o id informado.",
"request_id": "a1b2c3d4-0000-4000-8000-000000000000"
}| Campo | Tipo | Descrição |
|---|---|---|
status_code | integer | O mesmo status HTTP da resposta. |
error | string | Nome do status HTTP, em minúsculas, como bad_request ou not_found. |
message | string | Motivo em português, para exibir ou registrar. |
code | string | Código estável do erro, com PZ e três dígitos. Só vem nos erros que têm código. |
request_id | string | Identificador da chamada, o mesmo do cabeçalho X-Request-Id. Informe ao suporte para localizar a chamada. |
fields | array | Nos 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
| HTTP | Quando | Mensagem |
|---|---|---|
| 400 | O 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. |
| 404 | O caminho não existe. | Recurso não encontrado. |
| 413 | O corpo JSON passa de 1 MB. | O corpo da requisição passa do tamanho máximo aceito. |
| 415 | O 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
| Resposta | Como decidir |
|---|---|
Com code | Pelo 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 code | Pelo 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ção | Por fields, quando vem, com uma entrada por campo recusado. Sem fields, a recusa é do corpo inteiro, como em Respostas de qualquer rota. |
| Cartão recusado | Nã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. |
429 | Espere 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. |
5xx | Guarde o request_id. |
- Um
404sem código diz que o recurso não existe na sua conta: o id de outra conta também responde404. - Em
fields,nametraz o caminho do campo, comoitems[0].unit_price, e vemunknownquando a regra não aponta um campo. Nas regras de tipo e de tamanho,messagevem em inglês, comoRequired.
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.
| Resposta | Fica guardada | Nova tentativa |
|---|---|---|
Erro antes de a cobrança ou o estorno sair para a adquirente, como um 404 ou PZ201 | Não | Corrija a chamada e repita com a mesma chave. |
Resposta depois do envio, como o 201 com o cartão recusado, PZ403 ou PZ404 | Sim | Use outra chave, como em Quando o estorno não sai. |
Códigos mais comuns
| Código | HTTP | Mensagem |
|---|---|---|
PZ001 | 400 | A solicitação possui erros de validação. |
PZ010 | 400 | Envie o cabeçalho Idempotency-Key nesta operação. |
PZ201 | 400 | Token de cartão inválido ou vencido. Gere o token de novo. |
PZ750 | 400 | URL 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. |
PZ020 | 401 | Chave de API ausente. |
PZ021 | 401 | Chave de API inválida. |
PZ030 | 403 | Gateway suspenso para esta conta. Fale com o suporte PayZu. |
PZ031 | 403 | Esta conta só tem acesso de consulta. |
PZ032 | 403 | Cartão não habilitado para esta conta. Fale com o suporte para habilitar ou ofereça apenas Pix. |
PZ033 | 403 | Pix não habilitado para esta conta. Fale com o suporte para habilitar. |
PZ034 | 404 | Recorrência não ativada para esta conta. |
PZ011 | 409 | Idempotency-Key já usada com outra requisição. |
PZ012 | 409 | Requisição com esta Idempotency-Key ainda está em processamento. |
PZ113 | 409 | Esta fatura tem um pagamento aguardando confirmação. Tente novamente mais tarde. |
PZ400 | 409 | Só uma fatura paga pode ser estornada. |
PZ101 | 422 | Valor fora do limite desta conta. |
PZ202 | 503 | Não foi possível processar o cartão agora. Tente de novo. |
| Códigos | Onde valem |
|---|---|
PZ020, PZ021 e PZ030 | Em toda rota que usa a chave de API. Veja Autenticação. |
PZ034 | Nas rotas de planos, assinaturas e configurações. Veja Recorrência. |
Todos os códigos do PayZu Gateway estão no Catálogo de erros.