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

Como os documentos seguem um modelo imutável baseado em eventos (veja Conceitos Fundamentais), um passo incorreto na linha do tempo não pode ser corrigido no local.

CANCEL e recriação

Quando um documento possui dados incorretos (ex: participante errado), cancele-o e crie um substituto corrigido:

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": true,
       "isPublic": true
     },
     ...
   }

Um evento CANCEL precisa carregar um atributo de metadados reason não vazio; 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.

O evento RELATED cria um vínculo de rastreabilidade entre o documento cancelado e seu substituto, mantendo um histórico auditável.

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