Erros

// Um cliente que registra o requestId em sucesso e em falha, e que
// distingue erro retentavel de erro definitivo. Copie inteiro.

const BASE = "https://api.adigitalmax.com.br/v1";

export class ErroApi extends Error {
  constructor(status, corpo) {
    super(`${corpo.codigo}: ${corpo.title}`);
    this.name = "ErroApi";
    this.status = status;
    // Ramifique por codigo, e nunca por status nem por texto.
    this.codigo = corpo.codigo;
    this.requestId = corpo.requestId;
    this.detail = corpo.detail;
    this.erros = corpo.erros ?? [];
  }

  /** 429 e 5xx passam; o resto e defeito seu e retentar nao ajuda. */
  get retentavel() {
    return this.status === 429 || this.status >= 500;
  }
}

const dormir = (ms) => new Promise((r) => setTimeout(r, ms));

export async function chamar(caminho, opcoes = {}, tentativa = 1) {
  const resposta = await fetch(`${BASE}${caminho}`, {
    ...opcoes,
    headers: {
      Authorization: `Bearer ${process.env.ADM_CHAVE}`,
      Accept: "application/json",
      ...opcoes.headers,
    },
  });

  if (resposta.status === 204) return null;

  const corpo = await resposta.json();

  // Registre SEMPRE, e nao so no erro.
  console.log(
    JSON.stringify({
      nivel: resposta.ok ? "info" : "erro",
      rota: caminho,
      status: resposta.status,
      requestId: corpo.requestId ?? null,
      tentativa,
    })
  );

  if (resposta.ok) return corpo;

  const erro = new ErroApi(resposta.status, corpo);

  if (erro.retentavel && tentativa < 4) {
    // Respeite o Retry-After quando ele vier; ele nao e sugestao.
    const cabecalho = Number(resposta.headers.get("Retry-After"));
    const espera = Number.isFinite(cabecalho) && cabecalho > 0
      ? cabecalho * 1000
      : 2 ** tentativa * 500 + Math.random() * 300; // com jitter

    await dormir(espera);
    return chamar(caminho, opcoes, tentativa + 1);
  }

  throw erro;
}

#!/usr/bin/env python3
"""Cliente que registra o requestId e retenta so o que vale retentar."""

import json
import logging
import os
import random
import time

import requests

BASE = "https://api.adigitalmax.com.br/v1"
log = logging.getLogger("adigitalmax")


class ErroApi(Exception):
    def __init__(self, status: int, corpo: dict):
        self.status = status
        # Ramifique por codigo, e nunca por status nem por texto.
        self.codigo = corpo.get("codigo")
        self.request_id = corpo.get("requestId")
        self.detail = corpo.get("detail")
        self.erros = corpo.get("erros", [])
        super().__init__(f"{self.codigo}: {corpo.get('title')}")

    @property
    def retentavel(self) -> bool:
        """429 e 5xx passam; o resto e defeito seu e retentar nao ajuda."""
        return self.status == 429 or self.status >= 500


def chamar(metodo: str, caminho: str, tentativas: int = 4, **kwargs):
    for tentativa in range(1, tentativas + 1):
        resposta = requests.request(
            metodo,
            f"{BASE}{caminho}",
            headers={
                "Authorization": f"Bearer {os.environ['ADM_CHAVE']}",
                "Accept": "application/json",
                **kwargs.pop("headers", {}),
            },
            timeout=60,
            **kwargs,
        )

        if resposta.status_code == 204:
            return None

        corpo = resposta.json()

        # Registre SEMPRE, e nao so no erro.
        log.info(json.dumps({
            "rota": caminho,
            "status": resposta.status_code,
            "requestId": corpo.get("requestId"),
            "tentativa": tentativa,
        }))

        if resposta.ok:
            return corpo

        erro = ErroApi(resposta.status_code, corpo)

        if not erro.retentavel or tentativa == tentativas:
            raise erro

        # Retry-After nao e sugestao: obedeca quando vier.
        cabecalho = resposta.headers.get("Retry-After")
        espera = float(cabecalho) if cabecalho else 2 ** tentativa * 0.5 + random.random() * 0.3
        time.sleep(espera)

    raise RuntimeError("inalcancavel")

<?php
// Cliente que registra o requestId e retenta so o que vale retentar.

declare(strict_types=1);

final class ErroApi extends RuntimeException
{
    public function __construct(
        public readonly int $status,
        public readonly ?string $codigo,
        public readonly ?string $requestId,
        public readonly array $erros,
        string $mensagem
    ) {
        parent::__construct($mensagem);
    }

    /** 429 e 5xx passam; o resto e defeito seu e retentar nao ajuda. */
    public function retentavel(): bool
    {
        return $this->status === 429 || $this->status >= 500;
    }
}

function chamar(string $metodo, string $caminho, array $opcoes = [], int $tentativas = 4): ?array
{
    $base = 'https://api.adigitalmax.com.br/v1';

    for ($tentativa = 1; $tentativa <= $tentativas; $tentativa++) {
        $cabecalhosRecebidos = [];

        $ch = curl_init($base . $caminho);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST  => $metodo,
            CURLOPT_TIMEOUT        => 60,
            CURLOPT_HTTPHEADER     => array_merge(
                ['Authorization: Bearer ' . getenv('ADM_CHAVE'), 'Accept: application/json'],
                $opcoes['headers'] ?? []
            ),
            CURLOPT_HEADERFUNCTION => function ($ch, $linha) use (&$cabecalhosRecebidos) {
                $partes = explode(':', $linha, 2);
                if (count($partes) === 2) {
                    $cabecalhosRecebidos[strtolower(trim($partes[0]))] = trim($partes[1]);
                }
                return strlen($linha);
            },
        ]);
        if (isset($opcoes['body'])) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, $opcoes['body']);
        }

        $bruto  = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        curl_close($ch);

        if ($status === 204) {
            return null;
        }

        $corpo = json_decode((string) $bruto, true) ?: [];

        // Registre SEMPRE, e nao so no erro.
        error_log(json_encode([
            'rota' => $caminho, 'status' => $status,
            'requestId' => $corpo['requestId'] ?? null, 'tentativa' => $tentativa,
        ]));

        if ($status >= 200 && $status < 300) {
            return $corpo;
        }

        $erro = new ErroApi(
            $status,
            $corpo['codigo'] ?? null,
            $corpo['requestId'] ?? null,
            $corpo['erros'] ?? [],
            sprintf('%s: %s', $corpo['codigo'] ?? '?', $corpo['title'] ?? '?')
        );

        if (!$erro->retentavel() || $tentativa === $tentativas) {
            throw $erro;
        }

        // Retry-After nao e sugestao: obedeca quando vier.
        $espera = isset($cabecalhosRecebidos['retry-after'])
            ? (float) $cabecalhosRecebidos['retry-after']
            : (2 ** $tentativa) * 0.5 + (mt_rand(0, 300) / 1000);

        usleep((int) ($espera * 1_000_000));
    }

    throw new RuntimeException('inalcancavel');
}