Diagnosticar falhas

Leia os quatro campos

{
  "error": {
    "code": "invalid_uc",
    "message": "UC must contain ASCII digits only.",
    "retryable": false,
    "details": {}
  }
}

• code: identificador estável para lógica do cliente.
• message: explicação legível; pode evoluir, portanto não baseie lógica nela.
• retryable: indica se repetir mais tarde pode funcionar sem alterar o payload.
• details: contexto adicional, como jobId, campo ou status.

Sequência de diagnóstico

1. Registre HTTP, error.code e o cabeçalho X-Request-Id.
2. Se retryable for false, corrija a entrada ou o estado indicado antes de repetir.
3. Se for true, aplique espera crescente e limite a quantidade de tentativas.
4. Em trabalho terminal, preserve jobId, status, progress e error.details.

Exemplos frequentes

UC inválida

Remova espaços, pontuação e qualquer caractere que não seja dígito ASCII. Não converta para número, porque zeros à esquerda são significativos.

Trabalho duplicado

{
  "error": {
    "code": "job_already_exists",
    "message": "An active job already exists for this installation and job target.",
    "retryable": false,
    "details": {
      "jobId": "job_existente_01"
    }
  }
}

Consulte o jobId de details em vez de criar outro trabalho igual.

Credenciais recusadas

Em invalid_distributor_credentials, autorize novamente com o mesmo connectionId e a senha correta. Não repita o trabalho antes disso.

Serviço temporariamente indisponível

Em distributor_unavailable ou authentication_service_unavailable, respeite retryable, aguarde e tente novamente.

Quando acionar o suporte