Error Codes

{
  "success": false,
  "data": null,
  "error": {
    "message": "CPF não encontrado na base de dados"
  }
}

{
  "success": false,
  "error": "API Key não fornecida"
}

{
  "success": false,
  "error": "usage_unavailable",
  "message": "Não foi possível verificar o saldo de créditos. Tente novamente."
}

const res = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
  headers: { 'x-api-key': process.env.CPFHUB_API_KEY! },
  signal: AbortSignal.timeout(10_000),
})
const isJson = res.headers.get('content-type')?.includes('application/json')
const body = isJson ? await res.json() : null

if (res.ok) {
  console.log(body.data.name)
} else {
  // error is a string in some errors and an object { message } in the rest
  const message = typeof body?.error === 'string' ? body.error : body?.error?.message

  switch (res.status) {
    case 404:
      // CPF not found: no credit used
      break
    case 400:
    case 422:
      // Bad input: fix it, do not retry
      break
    case 401:
    case 403:
      // Bad key, no credits left or blocked account: do not retry
      throw new Error(message)
    case 429:
      // Per-minute limit: wait Retry-After seconds and retry
      await new Promise(r => setTimeout(r, Number(res.headers.get('retry-after') ?? 5) * 1000))
      break
    default:
      // 5xx: retry with backoff (see the table below)
      throw new Error(message ?? `HTTP ${res.status}`)
  }
}

import os, time, requests

res = requests.get(
    f"https://api.cpfhub.io/cpf/{cpf}",
    headers={"x-api-key": os.environ["CPFHUB_API_KEY"]},
    timeout=10,
)
is_json = "application/json" in res.headers.get("content-type", "")
body = res.json() if is_json else {}

if res.ok:
    print(body["data"]["name"])
else:
    error = body.get("error")
    message = error if isinstance(error, str) else (error or {}).get("message")

    if res.status_code == 404:
        print("CPF not found")
    elif res.status_code == 429:
        time.sleep(int(res.headers.get("retry-after", "5")))  # then retry
    elif res.status_code >= 500:
        pass  # retry with backoff
    else:
        raise RuntimeError(message)