Tratamento de erros

Trate erros corretamente com códigos de erro padrão.

Formato de resposta de erro

Todos os erros da API seguem um formato JSON consistente.

{
  "error": {
    "code": "error_code_here",
    "message": "A human-readable description of the error."
  }
}

Códigos de erro

Status	Código	Descrição
`401`	`missing_api_key`	Cabeçalho X-API-Key não fornecido.
`401`	`invalid_api_key`	A chave API fornecida é inválida, expirada ou revogada.
`402`	`quota_exceeded`	A cota mensal de requisições foi excedida.
`422`	`invalid_image`	Campo image ausente, base64 inválido ou excede 5MB.
`422`	`invalid_request`	O corpo da requisição não é JSON válido.
`502`	`inference_error`	O serviço ML está temporariamente indisponível. Tente novamente com backoff.

Exemplos de respostas de erro

Chave API ausente (401)

{
  "error": {
    "code": "missing_api_key",
    "message": "No API key provided. Include your key in the X-API-Key header."
  }
}

Imagem inválida (422)

{
  "error": {
    "code": "invalid_image",
    "message": "Image exceeds the maximum size of 5 MB."
  }
}

Erro de inferência (502)

{
  "error": {
    "code": "inference_error",
    "message": "ML inference service is temporarily unavailable. Please retry."
  }
}

Melhores práticas

Sempre verifique o código de status HTTP antes de analisar o corpo da resposta.
Implemente backoff exponencial para erros 502.
Monitore o uso de cota pelos cabeçalhos de resposta.
Não tente novamente erros 401 ou 422.
Use o campo error.code para tratamento programático de erros.

Exemplo de nova tentativa

Exemplo JavaScript com backoff exponencial:

async function analyzePalm(imageBase64, apiKey, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const res = await fetch(
      "https://api.trace-line.site/v1/palm/analyze",
      {
        method: "POST",
        headers: {
          "X-API-Key": apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ image: imageBase64 }),
      }
    );

    if (res.ok) return res.json();

    const error = await res.json();

    // Only retry on transient errors
    if (res.status !== 502) throw error;

    // Exponential backoff: 1s, 2s, 4s
    await new Promise((r) =>
      setTimeout(r, 1000 * Math.pow(2, attempt))
    );
  }

  throw new Error("Max retries exceeded");
}