Guías

Errores

Formato de error, códigos de estado y códigos de error de la API de Inspow.

La API usa códigos de estado HTTP estándar y devuelve los errores en JSON, siempre con la misma forma.

Formato de error

{
  "statusCode": 403,
  "code": "AUTH_INSUFFICIENT_PERMISSIONS",
  "message": "Descripción del error",
  "details": { },
  "timestamp": "2026-10-10T18:08:18.423Z",
  "path": "/api/v1/notification-preferences",
  "requestId": "101c888e-a926-451a-95db-9f62bf7bdc8b"
}

Campo	Contenido
`statusCode`	El código HTTP.
`code`	Código de error estable, pensado para que tu integración decida qué hacer (ver abajo).
`message`	Descripción legible. En errores de validación, los mensajes de cada campo van unidos con `;` .
`details`	Opcional: información extra (por ejemplo, el campo duplicado).
`timestamp`, `path`	Cuándo y en qué ruta ocurrió.
`requestId`	Identificador de la petición. Inclúyelo si reportas un problema a soporte.

Códigos HTTP frecuentes

HTTP	`code` habitual	Significado
`400`	`VALIDATION_FAILED` / `VALIDATION_INVALID_INPUT`	Petición inválida (datos mal formados o que no pasan la validación).
`401`	`AUTH_TOKEN_INVALID`	No autenticado: token ausente, inválido o caducado, o API Key inválida.
`402`	`SAAS_ACCOUNT_LOCKED`	La cuenta de la Organización está pausada por pago (por ejemplo, prueba vencida). `details.reason` dice el motivo. Ver Multi-tenant.
`403`	`AUTH_INSUFFICIENT_PERMISSIONS`	Sin permisos para el recurso (también: límite por hora de la API Key superado, IP o dominio no autorizados, organización cerrada).
`404`	`RESOURCE_NOT_FOUND`	Recurso no encontrado.
`409`	`RESOURCE_ALREADY_EXISTS`	El registro ya existe (valor duplicado).
`429`	`RATE_LIMIT_EXCEEDED`	Demasiadas peticiones (ver Rate limits).
`500`	`SYSTEM_INTERNAL_ERROR`	Error interno del servidor.
`503`	`SYSTEM_SERVICE_UNAVAILABLE`	Servicio no disponible (por ejemplo, organización suspendida).

Algunos errores de negocio traen un code más específico, por ejemplo INVOICE_ALREADY_PAID, SUBSCRIPTION_NOT_ACTIVE, TENANT_SUSPENDED o AUTH_INVALID_CREDENTIALS. Usa el code, no el texto de message, para tomar decisiones en tu código.