Tratamento de Erros

Quando uma requisição à API de integração falha, a resposta inclui um corpo JSON com informações sobre o erro.

Formato de erro

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or revoked API key"
}

Códigos de erro

Erros comuns e diagnóstico

401 — Chave não reconhecida

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or revoked API key"
}

Causas possíveis:

• A chave foi revogada a partir do painel de administração
• A chave tem uma data de expiração vencida
• Erro de formatação (espaços, caracteres extras)
• O dono da chave está inativo — nesse caso o message é API key owner is inactive or not found
• A API não conseguiu validar a chave naquele momento — nesse caso o message é API key validation failed; tente a requisição novamente

Uma requisição que não traz chave não recebe este 401. A API só lê x-api-key como chave quando o valor começa com rtn_sk_; qualquer outro valor conta como se não houvesse chave. Sem chave e sem x-tenant-id, a API responde 400 Bad Request com Missing required header: x-tenant-id; com x-tenant-id mas sem credenciais, responde 401.

Erros de projeto

Em GET /api/integration/activities/tasks e POST /api/integration/activity-results/tasks, x-project-id é opcional: os dois são endpoints project-optional. Quando o header é enviado, a API o verifica antes das permissões e do corpo. O 400 de um resultado sem activity_id não faz parte dessa verificação: chega depois da validação do corpo, então um erro no corpo é informado primeiro. Como cada chave escolhe o seu projeto é explicado em Escopo da chave.

403 — Permissão insuficiente

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Required permissions: activity:view"
}

Causas possíveis:

• A chave não inclui a permissão exigida para o endpoint
• Peça ao dono da chave que edite as permissões dela com PUT /api/api-keys/:id/permissions ou em Configurações → Chaves de API

400 — Erro de validação

A API responde 400 quando o corpo não está de acordo com o formato documentado.

Causas possíveis:

• Campos obrigatórios ausentes: occurred_at e task_result.result sempre; commerce_external_id apenas quando activity_id não é enviado (execuções independentes)
• Formato de data inválido (deve ser ISO 8601)
• activity_id não é um UUID válido
• Campos que não fazem parte do corpo documentado

422 — Estado não processável

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "La actividad no está en un estado válido para registrar resultado."
}

Causas possíveis:

• A atividade vinculada não está em um estado que aceita resultado. READY, DISPATCHED e RETRYING aceitam; COMPLETED também, e enviar de novo atualiza o resultado existente da atividade; CANCELED e FAILED não — message acima
• A data de execução da atividade já ultrapassou o corte de fim de dia — La actividad corresponde a un día ya cerrado y no admite registrar resultado. Depois desse corte, um fechamento automático é executado e pode registrar o resultado (como NOT_EXECUTED). Execuções independentes (STANDALONE, sem activity_id) estão isentas desta regra e da anterior
• O código de resultado de task_result.result não existe ou não está ativo — El tipo de resultado seleccionado no está activo. Veja Listar Configurações para obter códigos válidos
• O tipo de resultado exige task_result.future_scheduled_at e ele não foi enviado — Este tipo de resultado requiere una fecha comprometida.
• task_result.future_scheduled_at cai em um dia anterior a hoje, no fuso horário do tenant — La fecha programada no puede ser en el pasado.