Límites, cuotas e idempotencia

Tres controles distintos: rate limit por llave (peticiones por minuto), cuota mensual por cuenta (unidades consumidas) y límites de payload. Entender cuál aplica evita reintentos inútiles.

Rate limit por llave

El límite se aplica por llave de API, no por IP, para no castigar a clientes detrás de NAT. Usa un token bucket con la tasa del plan y una ráfaga adicional:

capacidad = rate_limit_rpm + burst
recarga  = rate_limit_rpm / 60 peticiones por segundo

Invitación · Beta: capacidad 70, recarga 1 petición/s

Cabeceras de límite y cuota

Cuando superas el rate limit, la respuesta es:

HTTP/1.1 429 Too Many Requests
Retry-After: 7
Content-Type: application/problem+json
X-Request-Id: req_b41c8e2a7f093d65

{
  "type": "https://api.434alchemycode.com/docs/errors/rate_limited",
  "title": "Demasiadas peticiones",
  "status": 429,
  "code": "RATE_LIMITED",
  "detail": "Superaste el límite por minuto. Respeta `Retry-After`.",
  "retryable": true,
  "request_id": "req_b41c8e2a7f093d65"
}

Cuota mensual

La cuota se mide en unidades, no en peticiones. Cada servicio declara cuántas consume; el buzón IMSS consume 2 porque sincroniza y descarga evidencias. La API evalúa la cuota antes de encolar el job: si no hay unidades, responde 429 QUOTA_EXCEEDED sin consumir ni crear job.

• Corte mensual: el periodo es el mes calendario en UTC; resets_at indica el inicio del siguiente.
• Sin arrastre: las unidades no usadas no se acumulan al mes siguiente.
• Errores no cobran: un job fallido no consume unidades; un job exitoso sí, aunque el sentido de la opinión sea negativo.
• Sandbox también mide: las consultas con ck_test_ consumen cuota (con datos simulados).
• Sin cargo en beta: las unidades se miden, pero no se genera cobro durante la beta.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json

{
  "type": "https://api.434alchemycode.com/docs/errors/quota_exceeded",
  "title": "Cuota mensual agotada",
  "status": 429,
  "code": "QUOTA_EXCEEDED",
  "detail": "Usaste 2000 de 2000 consultas del periodo. La cuota se renueva el 2026-11-01.",
  "retryable": false,
  "request_id": "req_7c1f9a3e5b2d8064",
  "quota": {
    "period_start": "2026-10-01T00:00:00+00:00",
    "period_end": "2026-11-01T00:00:00+00:00",
    "quota": 2000,
    "used": 2000,
    "remaining": 0,
    "percent": 100.0,
    "exceeded": true,
    "resets_at": "2026-11-01T00:00:00+00:00"
  }
}

Consulta tu estado en GET /v1/me (cuota y plan) y el detalle en GET /v1/usage (consumo por servicio, empresa, día y tokens de IA).

Idempotencia

Los seis endpoints asíncronos aceptan el encabezado Idempotency-Key. Sirve para que un reintento de red no cree dos jobs ni cobre dos veces.

curl -sS -X POST "https://api.434alchemycode.com/v1/sat/constancias" \
  -H "Authorization: Bearer $ALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2c7a-3d0e-4a51-9b0e-5c2a7f9d1e44" \
  -d '{"company_id": "9b2f5c1e-7a3d-4f8b-9c21-6d4e8a0b5f17"}' 

Usa un UUID v4 por operación de negocio y guárdalo junto con tu registro. No uses la misma clave para consultas distintas ni la reutilices entre empresas.

Tamaño de payload

Buenas prácticas

• Respeta Retry-After; no reintentes en paralelo tras un 429.
• Limita la concurrencia de tu cliente (4–8 en beta) y encola lo que exceda.
• Mide el consumo con /v1/usage; alerta al 80 % de la cuota.
• Reutiliza Idempotency-Key por operación de negocio, no por reintento manual.
• Divide lotes de 69-B en bloques de 1,000–2,000 RFC para controlar latencia y memoria.
• No uses sandbox para estimar cuota de producción: los datos son simulados, pero las unidades se descuentan.