Skip to main content
Todas as respostas de erro da API seguem um formato consistente para facilitar o tratamento programático e a depuração.

Estrutura da resposta de erro

{
  "message": "Descrição legível do erro",
  "code": "error_code",
  "details": [
    {
      "idempotencyKey": "evt-001",
      "errors": [
        {
          "code": "future_occurred_at",
          "message": "events occurring in the future cannot be recorded"
        }
      ]
    }
  ],
  "causations": [
    {
      "message": "Causa subjacente do erro",
      "code": "cause_code",
      "details": {}
    }
  ]
}

Campos

CampoTipoDescrição
messagestringDescrição legível do erro
codestringIdentificador único do tipo de erro — use para tratamento programático
detailsobjeto ou arrayContexto adicional (campos inválidos, erros por evento, etc.)
causationsarrayCadeia de erros relacionados — presente apenas quando há uma causa subjacente relevante

Códigos de status HTTP

StatusNomeDescrição
400Bad RequestRequisição malformada ou com parâmetros inválidos
401UnauthorizedAutenticação necessária ou credenciais inválidas
403ForbiddenSem permissão para acessar o recurso
404Not FoundRecurso não encontrado
500Internal Server ErrorErro interno — entre em contato com o suporte se persistir

Códigos de erro comuns

Eventos

CódigoCausa
failed_to_create_eventsUm ou mais eventos falharam na validação — nenhum foi processado
future_occurred_atO campo occurredAt está no futuro
duplicated_idempotency_keyJá existe um evento com esta chave de idempotência

Autenticação

CódigoCausa
invalid_api_keyChave de API não existe ou está incorreta
deactivated_api_keyChave desativada
revoked_api_keyChave revogada permanentemente
expired_api_keyChave expirada
ip_not_allowedIP não está na lista de IPs permitidos

Contratos

CódigoCausa
contract_must_have_plan_instancesContrato precisa de pelo menos um plano ativo para ser ativado
cannot_update_contracts_of_other_customersTentativa de alterar contrato de outro cliente

Próximos passos