PayZu OnboardingApoio

Erros


Nesta páginaFormatoDecida pelo códigoCódigos mais comunsErro da troca de token

Trate os erros do PayZu Onboarding pelo código estável do corpo de erro e use o texto só para exibir ou registrar, porque ele pode mudar sem aviso.

Formato

O corpo vem como application/problem+json, com os mesmos campos em toda rota. Um cancelamento com a versão desatualizada responde assim:

json
{
  "type": "https://api.sandbox.payzu.dev/errors/version_conflict",
  "title": "version_conflict",
  "status": 409,
  "detail": "O registro mudou desde a leitura. Releia e tente de novo.",
  "code": "version_conflict",
  "requestId": "req_8c41d0a2-6f3e-4b9a-9d17-0e5c2a7b3f61",
  "errors": [],
  "currentVersion": 4
}
CampoTipoDescrição
typestringURI do tipo do erro: o endereço do ambiente, /errors/ e o código. Não decida por ela.
titlestringResumo curto, igual ao código.
statusintegerO mesmo status HTTP da resposta.
detailstringMotivo em português, para exibir ou registrar.
codestringCódigo estável em snake_case.
requestIdstringIdentificador da requisição; informe ao suporte.
errors[]arrayEm validation_failed: path, code e message de cada campo recusado.
currentVersionintegerEm version_conflict: a versão vigente, para repetir a chamada.

Decida pelo código

Compare code com o Catálogo de erros. O status HTTP só indica a família do problema.

HTTPSignificadoExemplos
400Corpo ou parâmetro inválidos, inclusive JSON malformado ou campo que a rota não conhece.validation_failed, invalid_cursor, callback_url_invalid
401Credencial ausente, inválida ou vencida.missing_bearer, invalid_token, audience_not_resolved
403Acesso recusado: a PayZu recusou a credencial nesta rota, ou o tenant está desativado.audience_disabled
404Recurso inexistente para o seu acesso.proposal_not_found
409Conflito com o estado atual (versão, idempotência, proposta fechada) ou prefill.members sem companyData.version_conflict, client_code_conflict, proposal_not_open, journey_incomplete
410Prazo da proposta vencido.proposal_expired
422Pedido válido que não pode ser processado.contact_channel_unsupported
503Jornada embutida indisponível no ambiente.embed_unavailable

Um recurso que não é seu responde 404, nunca 403.

O tenant vem do token, e a proposta de outro tenant aparece como inexistente.

Códigos mais comuns

CódigoHTTPMensagem
validation_failed400Corpo ou parâmetros inválidos.
invalid_token401Token inválido, expirado ou emitido para outro serviço.
missing_bearer401Credencial ausente. Envie o header Authorization com Bearer.
proposal_not_found404Proposta não encontrada.
client_code_conflict409O clientCode já foi usado com outro conteúdo.
proposal_in_analysis409A proposta já foi enviada para análise e não pode mais ser cancelada.
proposal_not_editable409A proposta está em análise ou decidida e não aceita alterações agora.
proposal_not_open409A proposta já foi decidida, expirou ou foi cancelada.
version_conflict409O registro mudou desde a leitura. Releia e tente de novo.
write_conflict409Outra requisição gravou o mesmo recurso ao mesmo tempo. Releia e tente de novo.
proposal_expired410O prazo da proposta venceu.

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

Erro da troca de token

A troca de token é a única rota fora deste formato.

Gerar um token de acesso responde 400 com error e error_description. Os valores de error estão em Autenticação.