Tratamento de Erros

Padrões de tratamento de erros — decisões de retentativa, imutabilidade, CANCEL e recriação, deduplicação e limites de taxa.

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

Código de Status	Erro	Ação
`400`	Erro de validação	Abortar — corrija o payload e reenvie
`401` / `403`	Autenticação/autorização	Abortar — verifique as credenciais ou permissões
`404`	Recurso não encontrado	Abortar — verifique os IDs no caminho da requisição
`409`	`PENDING_PROCESS_CONFLICT_ERROR`	Retentar após 2-5 segundos — um processo em segundo plano está em andamento
`409`	Outros erros de conflito	Abortar — corrija o conflito de dados (ex: duplicata), não retente como está
`422`	Entidade não processável	Abortar — corrija a estrutura do payload
`429`	Limite de taxa excedido	Retentar com backoff exponencial
`500`	Erro interno do servidor	Retentar com backoff exponencial + `deduplicationId`
`502` / `503` / `504`	Gateway/serviço indisponível	Retentar com backoff exponencial + `deduplicationId`

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 (4xx exceto 409 PENDING_PROCESS_CONFLICT_ERROR e 429).

Mecânica do deduplicationId

O deduplicationId é sua chave de idempotência para operações de escrita:

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

O ID tem escopo por Integrador. Se o servidor já processou sua requisição, a retentativa retorna a resposta original em vez de criar uma duplicata. Isso é crítico para POST /documents e POST /documents/{id}/events.

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 /v1/documents/{wrongDocumentId}/events
   { "name": "CANCEL", ... }

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

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

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 integrador (consulte Limites de Taxa para a referência completa):

Ambiente	Limite
Test / Sandbox	5 requisições por segundo
Produção	10 requisições por segundo

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

On this page