Errores

{
  "type": "https://api.434alchemycode.com/docs/errors/credential_missing",
  "title": "Credenciales incompletas",
  "status": 422,
  "code": "CREDENTIAL_MISSING",
  "detail": "La empresa OMX2503255F9 no tiene configurado: e.firma (.cer/.key/contraseña). Cárgalas en POST /v1/companies/{id}/credentials.",
  "instance": "/v1/sat/constancias",
  "request_id": "req_8f2c1a4b7d9e3f60",
  "retryable": false,
  "docs_url": "https://api.434alchemycode.com/docs/errores/credential_missing",
  "missing": [
    "e.firma (.cer/.key/contraseña)"
  ],
  "company_id": "9b2f5c1e-7a3d-4f8b-9c21-6d4e8a0b5f17",
  "required": [
    "fiel"
  ]
}

{
  "type": "https://api.434alchemycode.com/docs/errors/validation_error",
  "title": "Datos inválidos",
  "status": 422,
  "code": "VALIDATION_ERROR",
  "detail": "Revisa los campos marcados en `errors`.",
  "instance": "/v1/companies",
  "request_id": "req_2b7e9d1c4a6f8035",
  "retryable": false,
  "docs_url": "https://api.434alchemycode.com/docs/errores/validation_error",
  "errors": [
    {"field": "rfc", "code": "VALUE_ERROR", "message": "RFC_INVALID"}
  ]
}

$status = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$body   = json_decode((string) $raw, true);

if ($status >= 400) {
    $code      = $body['code'] ?? 'UNKNOWN';
    $detail    = $body['detail'] ?? $body['title'] ?? 'Error desconocido';
    $requestId = $body['request_id'] ?? 'n/a';

    error_log("[{$code}] {$detail} (HTTP {$status}, request_id {$requestId})");

    if ($code === 'RATE_LIMITED') {
        $retryAfter = (int) ($body['retry_after'] ?? 5);
        sleep(max(1, $retryAfter));
        // reintenta la misma petición
    } elseif ($body['retryable'] ?? false) {
        // backoff exponencial
    } else {
        // error de negocio: no reintentes
    }
}

const data = await response.json().catch(() => ({}));

if (!response.ok) {
  console.error(`[${data.code ?? 'UNKNOWN'}] ${data.detail ?? response.statusText}`, {
    status: response.status,
    requestId: data.request_id,
    retryable: data.retryable,
  });
  if (data.code === 'RATE_LIMITED') {
    const seconds = Number(response.headers.get('retry-after') ?? 5);
    await new Promise((r) => setTimeout(r, seconds * 1000));
  }
  throw new Error(data.code ?? `HTTP_${response.status}`);
}

try:
    response = session.post(url, json=payload, timeout=(10, 45))
    response.raise_for_status()
except requests.HTTPError as exc:
    problem = exc.response.json()
    print(problem["code"], problem.get("detail"), problem.get("request_id"))
    if problem.get("retryable") or exc.response.status_code == 429:
        wait = float(exc.response.headers.get("Retry-After", 5))
        time.sleep(wait)
    raise

# -i muestra el status HTTP; el cuerpo de error viene en problem+json.
curl -i -sS -X POST "https://api.434alchemycode.com/v1/sat/constancias" \
  -H "Authorization: Bearer $ALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_id": "no-es-un-uuid"}'

# HTTP/1.1 422 Unprocessable Entity
# {"code":"VALIDATION_ERROR","detail":"Revisa los campos marcados en `errors`.","request_id":"req_...","errors":[...]}