Estructura de error

Toda respuesta de error sigue esta estructura:

{
  "status": "1",
  "message": "Descripción del error"
}

Algunas respuestas de error también incluyen el campo request_id si la request alcanzó la fase de validación de negocio.

{
  "status": "1",
  "message": "Consulta previa no encontrada",
  "request_id": "f7002954-8ec2-4248-9c8e-6625a2588117"
}

El campo status es siempre string: "0" indica éxito, "1" indica error. No hay códigos numéricos de error de aplicación.

Errores HTTP Estándar

Código	Significado	Causa Común	Solución
400 Bad Request	Formato de request inválido	JSON malformado o parámetros faltantes	Valida la estructura JSON y asegúrate de incluir todos los campos requeridos
401 Unauthorized	Autenticación fallida	JWT expirado o ausente	Obtén un nuevo token JWT o refresca el existente
403 Forbidden	Permiso denegado	API-key inválida o sin permisos en el endpoint	Verifica tu API-key y los permisos asignados
404 Not Found	Recurso no existe	Factura, empresa o transacción no encontrada	Verifica que los IDs sean correctos
409 Conflict	Conflicto de datos	Intento de pagar una factura ya pagada	Verifica el estado actual del recurso antes de intentar la operación
429 Too Many Requests	Rate limit excedido	Demasiadas requests en poco tiempo	Espera antes de realizar más requests o contacta soporte para aumentar tu límite
500 Internal Server Error	Error del servidor	Fallo interno no manejado	Reintenta más tarde. Si persiste, contacta soporte.
503 Service Unavailable	Servicio no disponible	Mantenimiento programado o incidente	Verifica el estado del servicio y reintenta más tarde

Mensajes de error por situación

La API no usa códigos numéricos de error propietarios. La causa se identifica por la combinación de HTTP status + campo message.

Autenticación

HTTP	message	Causa	Solución
401	Clave API no proporcionada	Falta el header api-key	Agrega el header api-key: {tu-uuid}
401	Clave API no corresponde al usuario autenticado	El JWT y el api-key pertenecen a usuarios distintos, el usuario está inactivo, o el api-key no existe	Verifica que JWT y api-key sean del mismo usuario y que el usuario esté activo (status=1)
403	Usuario no autorizado para este endpoint	No existe un registro User_Endpoint para este usuario y endpoint	Solicita a tu administrador que asigne el permiso en el endpoint correspondiente
404	Endpoint no encontrado	La URL no está registrada en la tabla Endpoint	Verifica que la URL sea correcta según la documentación

Validación de negocio — Consulta de factura

HTTP	message	Causa
500	Procedimiento almacenado no definido para el endpoint	El endpoint no tiene un SP configurado. Error de configuración del servidor.
400	Empresa no asociada al usuario	El API_User no tiene EmpresaSafe asignada
500	Conexión a base de datos no configurada	La empresa no tiene DBConection asignada
500	Error de conexion a base de datos	No se pudo conectar a SQL Server
400	Error en datos de consulta	Datos de entrada inválidos para el SP
500	Error ejecutando consulta	El SP retornó un error de ejecución
500	Error inesperado procesando consulta	Excepción no controlada en el servidor

Validación de negocio — Notificación de pago

HTTP	message	Causa
400	Consulta previa no encontrada	El request_id no corresponde a una transacción exitosa del mismo usuario, o no existe
400	Datos de consulta no encontrados	No hay BillQuery asociada al request_id
400	La factura no esta disponible para pago	La factura tiene Usable: false (ya pagada, vencida, u otra condición)
400	No se encontro liquidacion para la factura	El SP de liquidación no retornó datos
400	Pago no puede procesarse: SP de recibo de caja no configurado	Los datos de liquidación no incluyen el campo ReciboCaja ni ReciboCajaReal
500	Error de conexion al generar recibo de caja	Error de conexión SQL durante la generación del recibo
500	Error generando recibo de caja: {mensaje del SP}	El SP de recibo de caja retornó result != 1
500	Error procesando notificacion de pago	Error en el SP de liquidación o recibo

Validación de negocio — Reversa de pago

HTTP	message	Causa
500	Error procesando reversion de pago	Error en la conexión o ejecución del SP de reversa

Manejo recomendado de errores

import requests

BASE_URL = "https://TU-DOMINIO"
HEADERS = {
    "Authorization": "Bearer eyJ...",
    "api-key": "550e8400-e29b-41d4-a716-446655440000",
    "Content-Type": "application/json",
}

resp = requests.post(
    f"{BASE_URL}/corresponsales/api/factura/consulta/",
    headers=HEADERS,
    json={"invoice_id": "2025407608"},
)

body = resp.json()

if resp.status_code == 200 and body["status"] == "0":
    # Éxito
    data = body["data"]
    if data.get("Usable"):
        request_id = body["request_id"]
        # Proceder al pago...
    else:
        print("Factura no disponible para pago")
elif resp.status_code == 401:
    print("Error de autenticación:", body.get("message"))
    # Renovar token o verificar api-key
elif resp.status_code == 403:
    print("Sin permiso en este endpoint")
elif resp.status_code == 429:
    print("Rate limit excedido — espera antes de reintentar")
else:
    print(f"Error {resp.status_code}:", body.get("message"))

{
  "status": "1",
  "message": "Error description"
}

import requests

BASE_URL = "https://YOUR-DOMAIN"
HEADERS = {
    "Authorization": "Bearer eyJ...",
    "api-key": "550e8400-e29b-41d4-a716-446655440000",
    "Content-Type": "application/json",
}

resp = requests.post(
    f"{BASE_URL}/corresponsales/api/factura/consulta/",
    headers=HEADERS,
    json={"invoice_id": "2025407608"},
)

body = resp.json()

if resp.status_code == 200 and body["status"] == "0":
    data = body["data"]
    if data.get("Usable"):
        request_id = body["request_id"]
        # Proceed to payment...
    else:
        print("Invoice not available for payment")
elif resp.status_code == 401:
    print("Authentication error:", body.get("message"))
    # Renew token or verify api-key
elif resp.status_code == 403:
    print("No permission on this endpoint")
elif resp.status_code == 429:
    print("Rate limit exceeded — wait before retrying")
else:
    print(f"Error {resp.status_code}:", body.get("message"))