Erros

Os erros usam códigos de status 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>`. Use-o (ou o slug) para decidir o tratamento, não `title` nem `detail`
`title`	Resumo curto do tipo
`status`	O status HTTP
`detail`	Explicação legível desta ocorrência
`errors`	Problemas de validação: `pointer` (um JSON Pointer para o corpo da requisição, ou para a query ou as variáveis), `message` e `hint` opcional
`requestId`	Também no cabeçalho `x-request-id`. Informe-o ao suporte
`upgradeUrl`	Nos bloqueios de plano (`402`, `403 plan-upgrade-required`): onde adicionar um cartão ou fazer upgrade

Todos os problemas de validação de uma requisição são informados de uma vez, para que um cliente possa mostrar cada um deles ao lado do campo certo.

Tipos de erro

Status	Slug	Quando
400	`bad-request`	Requisição malformada, como um corpo que não é JSON válido
401	`unauthorized`	Credenciais ausentes, malformadas, 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 faça upgrade (o modo de teste não é afetado)
403	`forbidden`	Autenticado, mas sem autorização: uma permissão ausente, uma chave de API em um endpoint exclusivo do painel, uma requisição entre sites
403	`plan-upgrade-required`	O recurso não faz parte do plano do espaço de trabalho
403	`verification-required`	Um signatário enviou antes de verificar o código de uso único
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 gerar uma sessão para um destinatário que já assinou
409	`not-your-turn`	Um signatário enviou antes de os grupos de roteamento anteriores terminarem
409	`document-mismatch`	O documento mudou desde que foi exibido ao signatário (`viewedDocumentHash`)
409	`already-signed`	O endereço de e-mail já assinou por este link permanente
409	`in-use`	Exclusão de um modelo usado por envelopes ou links de assinatura
409	`no-draft`	Publicação de um modelo que não tem rascunho
409	`idempotency-in-progress`	Uma requisição com o mesmo `Idempotency-Key` ainda está em execução
409	`conflict`	Outros conflitos
410	`gone`	Uma sessão de assinatura que já foi usada ou expirou
413	`payload-too-large`	Um envio acima do limite (25 MB para arquivos de modelo)
415	`unsupported-media-type`	Um envio de 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 usado com uma requisição diferente
422	`conversion-failed`	Não foi possível converter um documento do Word
429	`rate-limited`	Requisições demais; aguarde os segundos de `Retry-After`, quando presente
500	`internal`	Erro inesperado. É seguro tentar de novo com o mesmo `Idempotency-Key`
501	`not-implemented`	O recurso existe no esquema, mas ainda não foi implementado (por exemplo, códigos por SMS)
503	`converter-unavailable`, `billing-unavailable`	Uma dependência está temporariamente indisponível; tente mais tarde

Tratando 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})`);
  }
}