Tratamento de Erros

Este guia cobre padrões de recuperação operacional para integração com a Carrot API.

Para códigos de erro dos endpoints e formato do payload, consulte Erros da API.

Classifique as falhas primeiro

• 4xx: problemas na requisição, dados ou integração. Corrija o payload ou o fluxo.
• 5xx: problemas transitórios na plataforma ou upstream. Retente com backoff.

Tabela de decisão de retentativas

Estratégia de retentativas

• Use backoff exponencial limitado para falhas transitórias (início em 1s, máximo 30s, máximo 5 retentativas).
• Reutilize o deduplicationId em chamadas retentáveis de criação/evento — veja abaixo.
• Pare de retentar em falhas de validação determinísticas — todo 4xx exceto 409 PENDING_PROCESS_CONFLICT_ERROR, 429 e o 403 de token expirado, que se resolve renovando o token em vez de retentar a mesma requisição.

Mecânica do deduplicationId

O deduplicationId é uma chave de criação única para operações de escrita:

1. Gere um ID único antes da primeira tentativa
2. Armazene-o junto com a operação no seu sistema
3. Reutilize o mesmo ID em cada retentativa dessa operação

O ID tem escopo por Integrador. Isso é crítico para POST /documents e POST /documents/{id}/events.

Uma resposta perdida de POST /documents não é, portanto, recuperável sozinho pela API. A única leitura de documento é GET /documents/{id}: não existe consulta por externalId nem por deduplicationId, e o 409 da retentativa não devolve o id. Envie externalId mesmo assim — é o que o suporte da Carrot precisa para localizar o documento — mas trate a recuperação do id como um pedido de suporte, não como uma chamada self-service. Não há forma segura de repetir a escrita por conta própria: reutilizar o deduplicationId devolve o 409 sem o id, e usar um novo cria um segundo documento. Registre o id da primeira resposta bem-sucedida antes de qualquer outra coisa, e mantenha o timeout da requisição generoso o bastante para que um commit lento não pareça uma resposta perdida.

Padrão de recuperação por imutabilidade

A API de documentos e eventos é intencionalmente append-only: novos eventos registram mudanças de estado, enquanto as submissões anteriores permanecem no histórico. Veja esse conceito em Conceitos Fundamentais. Quando um evento incorreto já foi aceito, o fluxo de correção é cancelar esse documento e enviar um substituto com os dados e eventos corretos.

CANCEL e recriação

Um evento UPDATE segue o mesmo conceito: registra uma mudança na visibilidade do documento ou na sua inclusão em buscas públicas, em vez de substituir dados já enviados. Corrigir um participante, um valor ou um evento anterior exige, portanto, cancelamento e nova submissão. A API pública não expõe operações PATCH, PUT ou DELETE de documento.

Antes de cancelar ou reimportar um documento real, verifique com a equipe responsável o estado dos certificados, créditos e auditorias associados. Confirme o procedimento de recuperação e como esses registros serão conciliados; o cancelamento sozinho não comprova a reversão dos efeitos posteriores.

Escolha a direção do relacionamento conforme os documentos em que ele precisa ficar registrado:

• Unidirecional (bidirectional: false): acrescenta a referência apenas ao documento indicado na requisição. O documento referenciado não recebe um novo evento. Use esse modo quando um documento precisa citar outro sem acrescentar um registro recíproco à linha do tempo dele.
• Bidirecional (bidirectional: true): também acrescenta um evento de referência de volta ao documento referenciado (RELATED por padrão). Use esse modo quando o relacionamento precisa aparecer nas duas linhas do tempo. Ambos os documentos precisam poder aceitar os respectivos eventos. Isso amplia seus históricos; não reescreve eventos existentes nem torna os documentos intercambiáveis.

Os dois modos exigem o mesmo dataset. Um evento RELATED pode ser acrescentado após CLOSE, mas nenhum novo evento pode ser acrescentado após CANCEL. Por isso, um relacionamento bidirecional com um documento cancelado é rejeitado: ele acrescentaria uma referência de volta a esse documento.

Na recuperação por substituição, o novo documento registra qual original substitui, enquanto o original cancelado não recebe novos eventos. O exemplo usa uma referência histórica unidirecional para esse propósito. Após confirmar o procedimento de recuperação, envie os dados corrigidos no mesmo dataset e inclua os demais campos obrigatórios do evento:

1. POST /documents/{wrongDocumentId}/events
   {
     "name": "CANCEL",
     "metadata": {
       "attributes": [
         { "name": "reason", "value": "Participante errado no documento original", "isPublic": true }
       ]
     },
     ...
   }

2. POST /documents
   { ...dados corrigidos do documento... }

3. POST /documents/{newDocumentId}/events
   {
     "name": "RELATED",
     "relatedDocument": {
       "documentId": "{wrongDocumentId}",
       "bidirectional": false
     },
     ...
   }

Um evento CANCEL precisa carregar um atributo de metadados não vazio chamado reason (em minúsculas); omiti-lo retorna 400 com The reason metadata is required for CANCEL events. Todo atributo de metadados também exige o próprio isPublic, então o objeto do atributo precisa estar completo.

Como nenhum evento de referência de volta é criado no modo unidirecional, omita isPublic, eventName, eventLabel, isBackReference e preserveSensitiveData dentro de relatedDocument. A API rejeita esses campos nesse modo. O próprio evento continua exigindo seu isPublic.

A referência preserva a conexão entre os dois registros; ela não corrige certificados, créditos ou resultados de auditoria associados. Guarde os dois IDs de documento no registro de recuperação.

Limites de taxa

A Carrot API aplica limites de taxa por cliente de API (consulte Limites de Taxa para a referência completa):

O limite é idêntico em teste e produção: o ambiente é selecionado pela sua credencial, não por uma faixa de throttling separada.

Implemente um token bucket ou leaky bucket no lado do cliente para respeitar os limites. Ao receber um 429, aplique backoff exponencial antes de retentar.

Observabilidade

Registre estes campos de cada resposta da API para depuração e suporte:

• Request ID — retornado nos headers da resposta
• Seu externalId — seu ID de correlação interno
• Campos do envelope de erro — errors[].code, errors[].id, errors[].timestamp
• Contagem de retentativas — quantas tentativas foram feitas
• Motivo da falha terminal — por que as retentativas pararam