Erros, Retry-After e retentativas

Todo erro da API vem no mesmo envelope: um código estável em error.code, uma mensagem em português, o request_id para citar ao suporte, retryable dizendo se vale repetir, e docs_url apontando para a seção desta página. O status HTTP diz a categoria; o código diz a causa. Nenhum erro consome crédito: só respostas 200 são cobradas.

O envelope

Campos de error, como o contrato os declara:

Programe contra error.code, não contra message: o texto pode mudar, o código não. Os códigos são um enum fechado do contrato; um código novo só entra com aviso no changelog.

Os códigos

• A confirmar — internal_error: O doc 12 §2.3 fixa o status 500 e deixa a coluna ‘quando’ vazia; não declara retryable, e nenhuma operação do openapi.json declara a resposta 500. O valor de retryable fica em aberto até o CTO ratificar.

Quando repetir

Repita só quando retryable for true, e sempre respeitando Retry-After quando ele vier:

• 429 rate_limited: você passou do limite de requisições por minuto da conta. Retry-After diz quantos segundos esperar. Reduza a concorrência em vez de só esperar; o limite é por conta e todas as chaves somam.
• 503 maintenance: a base está sendo atualizada. Retry-After diz quando voltar. A janela é mensal e anunciada em status.cnpj.ia.br.
• 504 upstream_timeout: a consulta estourou o tempo limite. Nada foi cobrado; repita com recuo exponencial.
• 500 internal_error: falha nossa. O contrato ainda não declara essa resposta nem o seu retryable; registre o request_id e cite ao suporte.

Não repita erros 4xx de validação, autenticação ou cobrança: a mesma chamada vai falhar de novo. Corrija o CNPJ, a chave ou o plano e chame outra vez.

import os, time, requests

HEADERS = {"Authorization": f"Bearer {os.environ['CNPJIA_KEY']}"}

def get(url, params=None, tentativas=4):
    for i in range(tentativas):
        r = requests.get(url, params=params, headers=HEADERS, timeout=10)
        if r.status_code == 200:
            return r.json()
        erro = r.json().get("error", {})
        if not erro.get("retryable"):
            raise RuntimeError(f"{r.status_code} {erro.get('code')}: {erro.get('message')} ({erro.get('request_id')})")
        espera = int(r.headers.get("Retry-After", 2 ** i))
        time.sleep(espera)
    raise RuntimeError("desistiu após retentativas")

const headers = { Authorization: `Bearer ${process.env.CNPJIA_KEY}` };

async function get(url, tentativas = 4) {
  for (let i = 0; i < tentativas; i++) {
    const res = await fetch(url, { headers });
    if (res.ok) return res.json();
    const { error } = await res.json();
    if (!error?.retryable) throw new Error(`${res.status} ${error?.code}: ${error?.message} (${error?.request_id})`);
    const espera = Number(res.headers.get("Retry-After") ?? 2 ** i);
    await new Promise((r) => setTimeout(r, espera * 1000));
  }
  throw new Error("desistiu após retentativas");
}

Boas práticas

• Trate not_found como resultado, não como falha: CNPJ com formato válido que não existe na base é uma resposta legítima.
• Guarde o request_id nos seus logs. É o que permite ao suporte achar a chamada.
• Leia X-RateLimit-Remaining para desacelerar antes do 429.
• Em lotes grandes, um 402 quota_exceeded no meio do processo é previsível: consulte GET /v1/usage antes de começar e compare com o custo estimado.

Relacionados

• Autenticação: os erros 401 e 403 em detalhe.
• Créditos, franquia e rate limit: 402, 429 e os headers de saldo.
• Dados e frescor: o que acontece na janela de manutenção.