Errores y Códigos HTTP

La API usa códigos de estado HTTP estándar. Todos los errores devuelven un cuerpo JSON con detalles.

Estructura de error

{
  "status": "error",
  "message": "Descripción legible del error",
  "error": "CODIGO_INTERNO"   // solo en algunos endpoints
}

Códigos HTTP

Código	Significado	Causa típica
200	OK	Petición exitosa
201	Created	Recurso creado exitosamente
400	Bad Request	Datos inválidos o campo requerido ausente
401	Unauthorized	Token ausente, inválido o expirado
403	Forbidden	Sin permisos para esa operación
404	Not Found	Recurso no encontrado
409	Conflict	Conflicto de datos (email duplicado, nombre de agencia ya existe)
422	Unprocessable Entity	Error de validación de campos
429	Too Many Requests	Límite de peticiones excedido
500	Internal Server Error	Error interno del servidor

Errores de validación (422)

{
  "status": "error",
  "message": "Validation failure",
  "errors": [
    {
      "field": "email",
      "message": "The email field must be a valid email address",
      "rule": "email"
    },
    {
      "field": "password",
      "message": "The password field must have at least 8 characters",
      "rule": "minLength"
    }
  ]
}

Códigos internos comunes

Código	Descripción
EMAIL_ALREADY_EXISTS	El email ya está registrado en el sistema
AGENCY_NAME_EXISTS	El nombre de agencia ya está en uso
AGENT_NOT_FOUND	El agente especificado no existe
PROPERTY_NOT_FOUND	La propiedad no fue encontrada
UNAUTHORIZED_AGENCY	No eres el administrador de esa agencia

Manejo de errores — Ejemplo

const response = await fetch('https://api.havi.app/api/agencies', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload)
})

if (!response.ok) {
  const error = await response.json()

  if (response.status === 409) {
    console.error('Nombre de agencia ya existe:', error.message)
  } else if (response.status === 401) {
    // Renovar token
    await refreshToken()
  } else {
    console.error('Error:', error.message)
  }
}

Rate Limiting

Los límites se devuelven en los headers de cada respuesta:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1715600000

Si superas el límite, recibirás un 429 Too Many Requests con el tiempo de espera.