Erros

Os erros utilizam códigos de estado HTTP e um corpo RFC 9457 com Content-Type: application/problem+json:

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/recipients/0/email", "message": "Invalid email address" },
    { "pointer": "/recipients", "message": "Missing recipient for role 'company'." },
    { "pointer": "/recipients/1/role", "message": "Unknown role 'cfo'.", "hint": "Template roles: client, company" }
  ],
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Membro	Significado
`type`	Identificador estável: `https://bonafidesign.com/problems/<slug>`. Decida o tratamento com base neste valor (ou no slug), não em `title` nem em `detail`
`title`	Resumo breve do tipo
`status`	O estado HTTP
`detail`	Explicação legível desta ocorrência
`errors`	Problemas de validação: `pointer` (um JSON Pointer para o corpo do pedido, ou para a query ou as variáveis), `message` e `hint` opcional
`requestId`	Também no cabeçalho `x-request-id`. Indique-o ao suporte
`upgradeUrl`	Nos bloqueios de plano (`402`, `403 plan-upgrade-required`): onde adicionar um cartão ou mudar de plano

Todos os problemas de validação de um pedido são comunicados de uma só vez, para que um cliente possa mostrar cada um deles junto ao campo certo.

Tipos de erro

Estado	Slug	Quando
400	`bad-request`	Pedido mal formado, como um corpo que não é JSON válido
401	`unauthorized`	Credenciais em falta, mal formadas, revogadas ou expiradas
402	`payment-required`	Um espaço de trabalho Free concluiu os envelopes incluídos neste período; adicione um cartão ou mude de plano (o modo de teste não é afetado)
403	`forbidden`	Autenticado, mas sem autorização: uma permissão em falta, uma chave de API num endpoint exclusivo do painel, um pedido entre sites
403	`plan-upgrade-required`	A funcionalidade não está incluída no plano do espaço de trabalho
403	`verification-required`	Um signatário submeteu antes de verificar o seu código de utilização única
404	`not-found`	O recurso não existe na sua organização, ou a rota não existe
409	`invalid-state`	A ação não é compatível com o estado atual, por exemplo anular um envelope concluído ou criar uma sessão para um destinatário que já assinou
409	`not-your-turn`	Um signatário submeteu antes de os grupos de encaminhamento anteriores terminarem
409	`document-mismatch`	O documento mudou desde que foi mostrado ao signatário (`viewedDocumentHash`)
409	`already-signed`	O endereço de e-mail já assinou através desta ligação permanente
409	`in-use`	Eliminação de um modelo utilizado por envelopes ou ligações de assinatura
409	`no-draft`	Publicação de um modelo que não tem rascunho
409	`idempotency-in-progress`	Um pedido com o mesmo `Idempotency-Key` ainda está em execução
409	`conflict`	Outros conflitos
410	`gone`	Uma sessão de assinatura que já foi utilizada ou expirou
413	`payload-too-large`	Um carregamento acima do limite (25 MB para ficheiros de modelo)
415	`unsupported-media-type`	Um carregamento de um tipo não suportado
422	`validation-error`	O corpo, a query ou as variáveis são inválidos; consulte `errors`
422	`idempotency-key-reused`	O mesmo `Idempotency-Key` foi utilizado com um pedido diferente
422	`conversion-failed`	Não foi possível converter um documento do Word
429	`rate-limited`	Demasiados pedidos; aguarde os segundos indicados em `Retry-After`, quando presente
500	`internal`	Erro inesperado. É seguro repetir com o mesmo `Idempotency-Key`
501	`not-implemented`	A funcionalidade existe no esquema, mas ainda não está implementada (por exemplo, códigos por SMS)
503	`converter-unavailable`, `billing-unavailable`	Uma dependência está temporariamente indisponível; tente mais tarde

Tratar erros

const res = await fetch('https://api.bonafidesign.com/v1/envelopes', { method: 'POST', headers, body });
if (!res.ok) {
  const problem = await res.json(); // application/problem+json
  const slug = problem.type.split('/').pop();
  if (slug === 'validation-error') {
    for (const e of problem.errors) form.setError(e.pointer, e.message);
  } else if (slug === 'payment-required') {
    showUpgrade(problem.upgradeUrl);
  } else {
    throw new Error(`${problem.title} (${problem.requestId})`);
  }
}