Saltar al contenido
DevFact

Documentación

Errores

El formato de los errores y cómo resolver los más comunes.

Formato

Todos los errores tienen la misma forma, con un code estable para que tu sistema decida qué hacer; message es para personas y puede cambiar. source dice de dónde viene: sri, validacion, motor o auth. solucion dice qué hacer y docUrl enlaza la explicación completa.

ErrorJSON
{
  "error": {
    "code": "SCOPE_INSUFICIENTE",
    "message": "La API key no tiene el permiso "emitir"",
    "details": {},
    "requestId": "8c1f0b8e-6a3d-4c50-9a77-2f1d6c0b9e21",
    "source": "auth",
    "docUrl": "https://api.devfact.fonles.com/v1/errores/SCOPE_INSUFICIENTE",
    "solucion": "Use una key con ese scope o cree una con POST /v1/api-keys y "scopes"."
  }
}
Si nos escribes por un error, incluye el requestId (también va en la cabecera X-Request-Id): con él encontramos tu petición sin que nos mandes datos de tu cliente.

Los más comunes

  • COMPROBANTE_INVALIDOHTTP: 422Qué hacer: Un campo no es válido. details.issues trae el path de cada uno (items.0.iva…). No se gastó número.
  • COMPROBANTE_DEVUELTOHTTP: 422Qué hacer: La recepción del SRI lo devolvió. Sigue details.accion: corrige y reintenta, o configura el secuencial.
  • COMPROBANTE_NO_AUTORIZADOHTTP: 422Qué hacer: El SRI no lo autorizó (firma, cálculos, clave…). Corrige y reintenta con el mismo número.
  • EMISOR_REQUERIDOHTTP: 422Qué hacer: La cuenta tiene varios emisores: agrega "emisor" con el RUC.
  • SECUENCIAL_NO_CONFIRMADOHTTP: 409Qué hacer: En producción falta confirmar desde qué número sigue esa serie (Emisores → Secuenciales).
  • IDEMPOTENCY_CONFLICTHTTP: 409Qué hacer: Usaste la misma Idempotency-Key con otro contenido: usa una nueva.
  • CERTIFICADO_VENCIDOHTTP: 422Qué hacer: Tu firma venció: sube la nueva en Emisores → Firma electrónica.
  • PAYLOAD_PURGADOHTTP: 410Qué hacer: Pasó la retención: el XML y el RIDE ya no están. Descárgalos antes o amplía la retención.
  • NO_AUTENTICADOHTTP: 401Qué hacer: Falta la cabecera Authorization: Bearer con tu clave.
  • API_KEY_INVALIDAHTTP: 401Qué hacer: La clave no existe o está mal copiada (o fue revocada).
  • SCOPE_INSUFICIENTEHTTP: 403Qué hacer: La clave no tiene el permiso necesario (por ejemplo, emitir con una clave sólo de consulta).
  • ENTORNO_NO_PERMITIDOHTTP: 403Qué hacer: Esa operación exige una clave fk_live_ (o fk_test_).
  • LIMITE_ANUAL_ALCANZADOHTTP: 403Qué hacer: Llegaste al tope de tu plan en producción. Cambia de plan en Facturación.
  • LIMITE_EXCEDIDOHTTP: 429Qué hacer: Más de 300 peticiones por minuto: espera Retry-After.
  • SERIE_OCUPADAHTTP: 503Qué hacer: Demasiadas emisiones a la vez en la misma serie: reintenta con la misma Idempotency-Key.

Códigos del SRI

En un rechazo del SRI, cada mensaje de details.mensajes trae su identificador (el código de la ficha técnica) con titulo, solucion y reintentable.

  • 35El XML no cumple el esquema. Suele ser un dato con formato inválido; el servicio valida antes, así que es raro.
  • 39Firma inválida: la firma venció, no es del RUC o la entidad no la reconoce. Revisa tu .p12.
  • 43Clave de acceso ya registrada: el SRI ya lo tenía. El servicio lo consulta y lo deja autorizado.
  • 45El número ya lo usó otro sistema. El servicio salta al siguiente libre; si se repite, configura el secuencial.
  • 52Diferencias en los cálculos. Con los totales calculados por el servicio no debería pasar: escríbenos.
  • 65Fecha de emisión fuera de plazo. Emite con la fecha de hoy.
  • 70En procesamiento: el SRI aún no termina. El servicio sigue consultando (202).