Erros

Formato de resposta de erro, códigos de erro, limites e padrões de recuperação.

Esta página resume os formatos padrão de erro e os modos de falha comuns para integrações com a Carrot API.

Formato da resposta de erro

Payload típico de erro:

{
  "statusCode": 400,
  "errors": [
    {
      "code": "BAD_REQUEST_ERROR",
      "message": "Invalid type on $input.name, expected to be (string)",
      "id": "3f6b0f2c-6d5f-4a3a-9f9a-1c2d3e4f5a6b",
      "timestamp": 1684766595000
    }
  ]
}

code é um membro de enum em SCREAMING_SNAKE — veja a tabela abaixo.
id é um identificador aleatório de 36 caracteres no formato hexadecimal 8-4-4-4-12.
timestamp é epoch em milissegundos, enviado como número JSON, não como string.
errors sempre contém exatamente uma entrada atualmente.

Códigos de erro

HTTP	Código	Significado
400	`BAD_REQUEST_ERROR`	O payload da requisição falhou na validação de schema.
400	`VALIDATION_ERROR`	O payload está bem formado mas viola uma regra de negócio.
401	(gateway)	Sem header `Authorization`, ou um valor bearer que não é um JWT decodificável.
403	(gateway)	Token decodificado mas rejeitado: expirado, assinatura inválida, escopo ou issuer errado.
403	`RESTRICTED_RESOURCE_ERROR`	Token válido sem permissão para este recurso ou ambiente.
404	`NOT_FOUND_ERROR`	O recurso não existe ou não é compartilhado com o proprietário do token.
405	`METHOD_NOT_ALLOWED_ERROR`	Método HTTP não suportado neste caminho.
409	`CONFLICT_ERROR`	A operação conflita com dados existentes — incluindo um `deduplicationId` repetido.
409	`PENDING_PROCESS_CONFLICT_ERROR`	O documento solicitado ainda está sendo processado. Tente novamente mais tarde.
429	(gateway)	A taxa de requisições excedeu o limite permitido para o cliente.
500	`INTERNAL_SERVER_ERROR`	Falha inesperada no servidor.
503	`SERVICE_UNAVAILABLE_ERROR`	Serviço temporariamente indisponível ou requisição excedeu a janela de processamento.
504	`GATEWAY_TIMEOUT_ERROR`	Timeout upstream/expiração de sessão ao completar a requisição.

As linhas marcadas com (gateway) são produzidas pela borda da API, não pelo serviço. Elas carregam um corpo simples {"message": "..."} — sem o envelope errors[] e sem campo code — então diferencie um 403 pelo formato do corpo, não apenas pelo status.

Para limites de taxa e cotas, consulte Limites de Taxa.

Para padrões de recuperação de erros e estratégias de retentativa, consulte Tratamento de Erros.

Formato da resposta de erro

Códigos de erro

On this page