Errores

Todos los errores tienen la misma forma y su code viene de un catálogo cerrado. Programa contra el code, no contra el message: el primero es contrato, el segundo es texto que puede cambiar.

{
  "error": {
    "code": "credential_invalid",
    "message": "El SII no aceptó esa clave",
    "run_id": "run_3kf82ncq7p1xw0a"
  }
}

Catálogo

Código	HTTP	Qué significa
`invalid_params`	`400`	Los parámetros no pasan el esquema del flujo, o falta uno que el portal exige. Revisa el cuerpo antes de reintentar: reintentar igual da lo mismo.
`credential_invalid`	`400`	El organismo rechazó la clave del titular. Hay que pedirla de nuevo por el widget; no se reintenta sola.
`credential_expired`	`400`	La credencial ya no sirve: caducó, fue revocada o la cuenta está bloqueada en el organismo. El titular tiene que resolverlo allá.
`portal_unavailable` reintentable no se factura	`502`	El portal del organismo no respondió o está caído. Es transitorio y no se factura.
`portal_changed` no se factura	`502`	El portal cambió y el flujo dejó de calzar. No es culpa tuya y no se factura; lo arreglamos nosotros.
`not_found`	`404`	No existe el run, la sesión o el recurso que pediste.
`rate_limited` reintentable	`429`	Demasiadas peticiones. Espera y reintenta con retroceso exponencial.
`flow_disabled`	`409`	El flujo existe pero está deshabilitado ahora mismo — mantención del organismo, o retirado del catálogo.
`internal_error` reintentable no se factura	`500`	Falla nuestra. No se factura y conviene reintentar.
`authentication_error`	`401`	Falta la credencial o no es válida.
`permission_denied`	`403`	La credencial es válida pero no alcanza para este endpoint.
`conflict`	`409`	Choca con el estado actual: una `Idempotency-Key` reusada con otro cuerpo, o una sesión que ya avanzó.

Qué reintentar

Sólo los marcados como reintentables: portal_unavailable, rate_limited, internal_error. Nacen de una falla pasajera —el portal caído, un pico de carga, un tropiezo nuestro— y la misma petición puede funcionar en un minuto.

El resto es terminal: reintentar invalid_params con el mismo cuerpo da invalid_params, y reintentar credential_invalid además acerca el bloqueo de la cuenta del titular en el organismo. Ahí no hay nada que reintentar: hay algo que corregir.

Cuando reintentes, manda la misma Idempotency-Key. Si la petición original sí llegó, recibirás el run que ya existe en vez de crear —y pagar— uno nuevo.

Qué se factura

Un run que falla por causas nuestras o del organismo no se cobra: portal_changed, portal_unavailable, internal_error. El resto sí, porque significa que el trabajo se hizo y la respuesta es legítima —una clave equivocada consumió una sesión real contra el portal.