KinologydevelopersReferência da API v1.0
FUNDAMENTOS

Falhas e retentativas

Identifique a causa antes de repetir. Preserve a intenção da operação.

Leia HTTP e CODIGO_ERRO

Erros JSON preservam status: fail, code: -1, VERSAO_SCHEMA, CODIGO_ERRO, message, ID_CORRELACAO e ID_REQUISICAO. Corrija credencial, conta, permissão, versão e entrada antes de chamar novamente. 409 IDEMPOTENCIA_CONFLITANTE exige revisar chave e corpo; não ignore o conflito.

Espere com limite

Para 429 e 503, respeite Retry-After (atualmente 1 segundo), use espera progressiva com jitter e limite, por exemplo, de quatro tentativas. 409 PDF_EM_GERACAO representa o mesmo pedido pendente: repita o pedido com espera progressiva e limite, sem tratar como conflito de versão. Nas escritas, mantenha corpo e Idempotency-Key. Timeout não implica que nada foi confirmado.

Envie somente identificadores ao suporte

Informe HTTP, CODIGO_ERRO, ID_CORRELACAO e ID_REQUISICAO. Não anexe chave, ticket, URL_PDF, CSV nem conteúdo clínico. Para falhas persistentes após tentativas limitadas, entre em contato com a Kinology.

Exemplos de erros confirmados no código
HTTPCODIGO_ERROAção
400CAMPO_INVALIDORevise campos, filtros, datas e cursor.
401CREDENCIAL_INVALIDASolicite à Kinology uma credencial válida.
403PERMISSAO_NEGADAConfirme a concessão e a permissão da conta.
404ACESSO_INDISPONIVELPara ticket expirado ou indisponível, solicite outro PDF.
408PRAZO_LEITURA_EXCEDIDOEnvie o corpo completo dentro do prazo.
409VERSAO_CONFLITANTEConsulte a versão atual antes de revisar a atualização.
413PAYLOAD_INVALIDOReduza o corpo ou divida o CSV.
415FORMATO_NAO_SUPORTADOEnvie application/json sem compressão.
422SEM_DADOS_PDFReduza o período ou revise as seções.
429LIMITE_CONCORRENCIARespeite Retry-After e reduza o paralelismo.
503SERVICO_INDISPONIVELRespeite Retry-After; repita com espera progressiva e limite de tentativas.
Envelope de erro sintético
{
  "status": "fail",
  "code": -1,
  "VERSAO_SCHEMA": "1.0",
  "ID_CORRELACAO": "INTEGRACAO-EXEMPLO-001",
  "ID_REQUISICAO": "11111111-1111-4111-8111-111111111111",
  "CODIGO_ERRO": "VERSAO_CONFLITANTE",
  "message": "Versão do registro divergente."
}
Retentativa limitada · JavaScript no servidor
// Preserve o mesmo corpo e Idempotency-Key nas escritas.
for (let tentativa = 0; tentativa < 4; tentativa++) {
  const response = await executarMesmoPedido();
  const erro = await response.clone().json().catch(() => ({}));
  const pendente = response.status === 409 && erro.CODIGO_ERRO === "PDF_EM_GERACAO";
  if (![429, 503].includes(response.status) && !pendente) break;
  const retryAfter = response.headers.get("Retry-After");
  const segundos = Number(retryAfter);
  const minimo = Number.isFinite(segundos) ? segundos * 1000
    : Math.max(0, Date.parse(retryAfter ?? "") - Date.now()) || 1000;
  if (tentativa === 3) throw new Error("Limite de tentativas");
  await new Promise(r => setTimeout(r, Math.max(minimo, 1000 * 2 ** tentativa) + Math.random() * 300));
}
Todos os exemplos são sintéticos. Execute chamadas reais somente no seu servidor, em ambiente autorizado.
Experimentar no laboratório