Referencia

Planes y límites

Cada plan define dos límites: la tasa de solicitudes por minuto (compartida entre todas tus llaves) y el número de RFCs distintos que puedes operar en producción (ver Padrón de RFCs).

Plan	Solicitudes / min	RFCs en padrón
Starter	60	100
Pro	300	500
Scale	1,200	1,500
Modo prueba (`sk_test_…`)	10	1

Al rebasar la tasa recibes 429 con retry-after; al rebasar el padrón, 403 rfc_limit_reached. Algunos servicios además requieren un plan mínimo (p. ej. Infonavit requiere Pro o superior → 403 plan_gate).

Referencia

Padrón de RFCs

En producción, cada RFC distinto que operas se registra automáticamente en tu padrón la primera vez que lo usas, y cuenta contra el límite de tu plan. Todos los servicios consumen slot de padrón excepto EFOS (la consulta de listas negras es libre — úsala para validación masiva de proveedores sin costo de padrón).

Cuando intentas operar un RFC nuevo y ya llegaste al límite, la API responde 403:

403 — rfc_limit_reached

{
  "ok": false,
  "code": "rfc_limit_reached",
  "rfc": "XAXX010101000",
  "limit": 100,
  "plan": "starter",
  "upgrade_url": "https://subalans.com/desarrolladores"
}

Cooldown al dar de baja. Puedes dar de baja RFCs de tu padrón desde el dashboard para liberar espacio, pero el slot queda en cooldown de 7 días: el RFC dado de baja no libera su lugar de inmediato. Planea las rotaciones con anticipación.

Los RFCs que ya están en tu padrón siguen operando normal; el límite sólo bloquea RFCs nuevos. El modo prueba no usa el padrón.

Referencia

Resumen de códigos

HTTP	Cuerpo	Acción del cliente
200	`{ ok: true, ... }`	Procesar.
400	`{ ok: false, error }`	Corregir la petición. En Buzón y CFDI los errores de credencial llegan aquí (400 con `code: "credencial"`), no como 422.
401	`{ error }`	Revisar token: ausente, inválido, revocado o vencido (`expires_at`).
403	`{ ok: false, code, error, ... }`	`plan_gate` (servicio requiere plan superior; trae `min_plan` + `upgrade_url`), `key_scope_denied` (trae `allowed_services`) o `rfc_limit_reached` (trae `rfc`, `limit`, `plan`, `upgrade_url`).
422	`{ ok: false, code, error }`	Pedir al usuario corregir credencial (endpoints de PDF).
429	`{ error, plan, rate_per_min }` + `retry-after`	Esperar y reintentar, o subir de plan.
502 / 504	`{ ok: false, code: "tecnico"/"timeout", error }`	Reintentar con backoff.
503	`{ ok: false, code: "tecnico" \| "rfc_registry_unavailable", error }` + `retry-after`	Rate limiter caído (reintenta en 2 s) o padrón de RFCs no disponible (reintenta en 5 s).

Referencia

Health checks

La API expone GET /api/v1/health (sin autenticación) para monitoreo. Devuelve el estado de cada servicio.

GET /api/v1/health

{ "ok": true, "services": { "constancia": true, "opinion": true, "opinion-imss": true, "infonavit": true, "buzon": true, "cfdi": true, "efos": true } }

Referencia

Buenas prácticas

Llama desde tu backend. Nunca expongas el token ni credenciales en el cliente.
Distingue 4xx de 5xx. 4xx = el usuario debe actuar (no reintentar igual); 5xx = el portal del gobierno falló (reintentar con backoff).
Muestra el campo error tal cual. Ya viene en español y es accionable.
Valida la e.firma antes de pedirla. La API rechaza credenciales mal formadas en milisegundos: aprovéchalo para dar feedback inmediato.
No abras documentos del Buzón. La API entrega metadatos a propósito; abrir el documento genera un acuse legal de notificación.
Timeouts generosos (≥180 s) para IMSS e Infonavit.
EFOS para validación masiva de proveedores: es instantáneo y no consume credenciales.