Errores

Referencia completa de errores HTTP y códigos SUNAT en Facturalo API. 401 token inválido, 422 validación, errores de SUNAT y cómo manejarlos en tu integración.

Todas las respuestas de error incluyen success: false y un campo message descriptivo. Los errores de validación (422) incluyen además un campo errors con detalles por campo.

Los errores traen además requestId (también en el header X-Request-Id). Compártelo con soporte o consúltalo con GET /peticiones/{id}. Ver Request ID.

Códigos HTTP

200 — OK — Petición exitosa.
201 — Created — Recurso creado correctamente (empresa, establecimiento).
401 — Unauthorized — Token ausente, inválido o del tipo equivocado para este endpoint.
404 — Not Found — Recurso no encontrado.
422 — Unprocessable — Datos de entrada inválidos. Revisa el campo errors.
500 — Server Error — Error interno. Reintenta con backoff exponencial.

Error de validación (422)

Respuesta 422json

{
  "success": false,
  "message": "Los datos enviados no son válidos.",
  "errors": {
    "documento.cliente.numeroDocumento": [
      "El número de documento debe tener 11 dígitos para tipo RUC."
    ],
    "documento.items": [
      "El campo items es requerido."
    ]
  }
}

Error de autenticación (401)

Respuesta 401json

{
  "success": false,
  "message": "Token inválido o expirado."
}

Errores SUNAT

Cuando SUNAT rechaza un comprobante, la respuesta HTTP es 200 (la petición a la API fue exitosa), pero el campo estado será RECHAZADA y el campo sunat.codigo contendrá el código de error de SUNAT.

Rechazo SUNAT (HTTP 200, estado RECHAZADA)json

{
  "success": true,
  "message": "El comprobante fue rechazado por SUNAT.",
  "data": {
    "estado": "RECHAZADA",
    "entorno": "demo",
    "documento": {
      "id": "9c948140-674e-11f1-85b5-d764057e10c4",
      "serie": "F001",
      "correlativo": "00000001",
      "tipo": "FACTURA"
    },
    "sunat": {
      "codigo": "2800",
      "mensaje": "El número de RUC del receptor no existe en el padrón de contribuyentes de la SUNAT",
      "notas": []
    }
  }
}

Número ya usado en SUNAT (1033)

Respuesta HTTP 200 con success: false, estado: NO_ENVIADA y sunat.codigo: "1033": la serie y el correlativo ya existen en SUNAT desde otro sistema. Elimina el comprobante y emítelo con otro correlativo. Detalle en Estados.

Número ya usado (HTTP 200, estado NO_ENVIADA)json

{
  "success": false,
  "message": "El número F002-00000001 ya fue emitido en SUNAT el 16/12/2017 desde otro sistema. Este comprobante no se envió: emítelo con otro correlativo.",
  "data": {
    "estado": "NO_ENVIADA",
    "entorno": "prod",
    "documento": {
      "id": "fb904030-dbb1-11f1-adbc-a3ddf1304e3d",
      "serie": "F002",
      "correlativo": "00000001",
      "tipo": "FACTURA",
      "estado": "NO_ENVIADA"
    },
    "sunat": {
      "estado": "NO_ENVIADA",
      "codigo": "1033",
      "mensaje": "El número F002-00000001 ya fue emitido en SUNAT el 16/12/2017 desde otro sistema. Este comprobante no se envió: emítelo con otro correlativo.",
      "notas": []
    }
  }
}