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.
| HTTP | CODIGO_ERRO | Ação |
|---|---|---|
| 400 | CAMPO_INVALIDO | Revise campos, filtros, datas e cursor. |
| 401 | CREDENCIAL_INVALIDA | Solicite à Kinology uma credencial válida. |
| 403 | PERMISSAO_NEGADA | Confirme a concessão e a permissão da conta. |
| 404 | ACESSO_INDISPONIVEL | Para ticket expirado ou indisponível, solicite outro PDF. |
| 408 | PRAZO_LEITURA_EXCEDIDO | Envie o corpo completo dentro do prazo. |
| 409 | VERSAO_CONFLITANTE | Consulte a versão atual antes de revisar a atualização. |
| 413 | PAYLOAD_INVALIDO | Reduza o corpo ou divida o CSV. |
| 415 | FORMATO_NAO_SUPORTADO | Envie application/json sem compressão. |
| 422 | SEM_DADOS_PDF | Reduza o período ou revise as seções. |
| 429 | LIMITE_CONCORRENCIA | Respeite Retry-After e reduza o paralelismo. |
| 503 | SERVICO_INDISPONIVEL | Respeite Retry-After; repita com espera progressiva e limite de tentativas. |
{
"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."
}// 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));
}