PayZu OnboardingApoio
Erros
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
}| Campo | Tipo | Descrição |
|---|---|---|
type | string | URI do tipo do erro: o endereço do ambiente, /errors/ e o código. Não decida por ela. |
title | string | Resumo curto, igual ao código. |
status | integer | O mesmo status HTTP da resposta. |
detail | string | Motivo em português, para exibir ou registrar. |
code | string | Código estável em snake_case. |
requestId | string | Identificador da requisição; informe ao suporte. |
errors[] | array | Em validation_failed: path, code e message de cada campo recusado. |
currentVersion | integer | Em 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.
| HTTP | Significado | Exemplos |
|---|---|---|
400 | Corpo ou parâmetro inválidos, inclusive JSON malformado ou campo que a rota não conhece. | validation_failed, invalid_cursor, callback_url_invalid |
401 | Credencial ausente, inválida ou vencida. | missing_bearer, invalid_token, audience_not_resolved |
403 | Acesso recusado: a PayZu recusou a credencial nesta rota, ou o tenant está desativado. | audience_disabled |
404 | Recurso inexistente para o seu acesso. | proposal_not_found |
409 | Conflito 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 |
410 | Prazo da proposta vencido. | proposal_expired |
422 | Pedido válido que não pode ser processado. | contact_channel_unsupported |
503 | Jornada 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ódigo | HTTP | Mensagem |
|---|---|---|
validation_failed | 400 | Corpo ou parâmetros inválidos. |
invalid_token | 401 | Token inválido, expirado ou emitido para outro serviço. |
missing_bearer | 401 | Credencial ausente. Envie o header Authorization com Bearer. |
proposal_not_found | 404 | Proposta não encontrada. |
client_code_conflict | 409 | O clientCode já foi usado com outro conteúdo. |
proposal_in_analysis | 409 | A proposta já foi enviada para análise e não pode mais ser cancelada. |
proposal_not_editable | 409 | A proposta está em análise ou decidida e não aceita alterações agora. |
proposal_not_open | 409 | A proposta já foi decidida, expirou ou foi cancelada. |
version_conflict | 409 | O registro mudou desde a leitura. Releia e tente de novo. |
write_conflict | 409 | Outra requisição gravou o mesmo recurso ao mesmo tempo. Releia e tente de novo. |
proposal_expired | 410 | O 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.