Boas práticas: reenvios, limites, segurança e custos

// chamar(): repete a chamada quando vale a pena (429 de limite por minuto, 502/503, falha de rede)
// e devolve a resposta para os outros casos. Não repete erros 4xx de validação: eles vão falhar de novo.
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function chamar(url, init = {}, { tentativas = 4, repetirRede = init.method === undefined || init.method === 'GET' } = {}) {
  for (let i = 1; ; i++) {
    let res;
    try {
      res = await fetch(url, init);
    } catch (erro) {
      // Sem resposta: num POST não dá para saber se a tarefa foi criada (veja "Reenvios sem cobrança dupla")
      if (!repetirRede || i >= tentativas) throw erro;
    }
    if (res) {
      const temporario = res.status === 429 || res.status === 502 || res.status === 503;
      if (!temporario || i >= tentativas) return res;
      const corpo = await res.clone().json().catch(() => ({}));
      if (corpo.error?.code === 'test_limit') return res; // chave de teste: limite do dia, não adianta repetir
    }
    const retryAfter = Number(res?.headers.get('retry-after'));
    await sleep(retryAfter > 0 ? retryAfter * 1000 : Math.min(30000, 1000 * 2 ** (i - 1)) + Math.random() * 300);
  }
}

// Exemplo
const res = await chamar('https://convertaja.com.br/v1/cep/01310100', { headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` } });
console.log(res.status, await res.json());

# chamar(): repete a chamada quando vale a pena (429 de limite por minuto, 502/503, falha de rede)
# e devolve a resposta para os outros casos. Não repete erros 4xx de validação: eles vão falhar de novo.
import os
import random
import time
import requests


def chamar(method, url, tentativas=4, repetir_rede=None, **kwargs):
    if repetir_rede is None:
        repetir_rede = method.upper() == "GET"  # num POST sem resposta não dá para saber se a tarefa foi criada
    kwargs.setdefault("timeout", 60)
    for i in range(1, tentativas + 1):
        try:
            res = requests.request(method, url, **kwargs)
        except requests.ConnectionError:
            if not repetir_rede or i == tentativas:
                raise
            res = None
        if res is not None:
            temporario = res.status_code in (429, 502, 503)
            if not temporario or i == tentativas:
                return res
            if res.headers.get("Content-Type", "").startswith("application/json") and res.json().get("error", {}).get("code") == "test_limit":
                return res  # chave de teste: limite do dia, não adianta repetir
        retry_after = int(res.headers.get("Retry-After", "0")) if res is not None else 0
        time.sleep(retry_after if retry_after > 0 else min(30, 2 ** (i - 1)) + random.random() * 0.3)


# Exemplo
res = chamar("GET", "https://convertaja.com.br/v1/cep/01310100", headers={"Authorization": f"Bearer {os.environ['CONVERTAJA_KEY']}"})
print(res.status_code, res.json())

<?php
// chamar(): repete a chamada quando vale a pena (429 de limite por minuto, 502/503)
// e devolve [status, corpo] nos outros casos. Não repete erros 4xx de validação: eles vão falhar de novo.
function chamar(string $url, array $opcoes = [], int $tentativas = 4): array {
  for ($i = 1; ; $i++) {
    $retryAfter = 0;
    $ch = curl_init($url);
    curl_setopt_array($ch, $opcoes + [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 60]);
    curl_setopt($ch, CURLOPT_HEADERFUNCTION, function ($ch, $linha) use (&$retryAfter) {
      if (stripos($linha, 'Retry-After:') === 0) $retryAfter = (int) trim(substr($linha, 12));
      return strlen($linha);
    });
    $corpo = json_decode((string) curl_exec($ch), true);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $temporario = in_array($status, [429, 502, 503], true) && ($corpo['error']['code'] ?? '') !== 'test_limit';
    if (!$temporario || $i >= $tentativas) return [$status, $corpo];
    sleep($retryAfter > 0 ? $retryAfter : min(30, 2 ** ($i - 1)));
  }
}

// Exemplo
[$status, $cep] = chamar('https://convertaja.com.br/v1/cep/01310100', [
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVERTAJA_KEY')],
]);
echo "$status {$cep['cidade']}\n";

// Toda resposta autenticada traz o saldo: use para avisar antes de faltar crédito
const res = await fetch('https://convertaja.com.br/v1/me', { headers: { Authorization: `Bearer ${process.env.CONVERTAJA_KEY}` } });
const saldo = Number(res.headers.get('x-credits-remaining'));
if (saldo < 200) console.warn(`Atenção: restam ${saldo} créditos`);

# Créditos e chamadas por dia e por endpoint (padrão: últimos 30 dias)
curl "https://convertaja.com.br/v1/usage?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $CONVERTAJA_KEY"