Manejo de errores

Cotizave usa códigos de respuesta HTTP estándar y un formato consistente de errores JSON para que puedas manejar fallos de forma predecible.

Formato de errores

Todos los errores devuelven un JSON con esta estructura:

{
  "code": "string_identificador_del_error",
  "message": "Descripción legible del problema."
}

Campos:

• code: identificador estable en formato snake_case. Úsalo en tu código para lógica condicional.
• message: descripción para desarrolladores. No la muestres directamente al usuario final.

Códigos de estado HTTP

Errores comunes

400 Bad Request

Request mal formateado o con parámetros inválidos.

{
  "code": "invalid_format",
  "message": "Amount must be a number.",
  "field": "amount"
}

Posibles code específicos:

• invalid_format: el valor de un campo tiene formato incorrecto. Incluye el campo en field.
• missing_field: falta un campo requerido. Incluye el campo en field.
• validation_failed: validación de negocio fallida.

Cómo responder: revisa los parámetros que estás enviando. Probablemente un typo, un valor no soportado o un formato incorrecto.

401 Unauthorized

Problema con la autenticación.

{
  "code": "invalid_api_key",
  "message": "API key is missing, invalid, or revoked."
}

Posibles code específicos:

• invalid_api_key: el header X-API-Key falta, tiene formato incorrecto (no empieza con ctz_live_, CRC32 inválido) o la key no existe en la base de datos
• key_revoked: la key fue revocada explícitamente desde el dashboard

Cómo responder: verifica tu API Key. Si fue revocada, crea una nueva.

403 Forbidden

La autenticación es válida pero no tienes acceso al recurso.

{
  "code": "forbidden",
  "message": "Access denied."
}

Posibles code específicos:

• forbidden: acceso denegado al recurso
• account_inactive: la cuenta está suspendida o baneada
• not_available: el producto o endpoint no está disponible para tu plan o país

Cómo responder: verifica el estado de tu cuenta en el dashboard.

404 Not Found

El recurso solicitado no existe.

{
  "code": "resource_not_found",
  "message": "The requested resource was not found."
}

Cómo responder: verifica el path, el market o el ID del recurso.

422 Unprocessable Entity

Los parámetros son válidos en formato pero no tienen sentido lógico (ej: spread contra un market no disponible).

{
  "code": "reference_unavailable",
  "message": "Reference rate (BCV) is not available right now."
}

Posibles code específicos (422):

• reference_unavailable: la tasa BCV no está disponible (solo en /v1/fx/spread)
• compared_unavailable: la tasa del market comparado no está disponible (solo en /v1/fx/spread)

Cómo responder: reintenta en unos minutos.

429 Too Many Requests

Rate limit excedido.

{
  "code": "rate_limit_exceeded",
  "message": "Límite de solicitudes excedido."
}

Headers relevantes: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After.

Cómo responder: respeta Retry-After, implementa backoff exponencial, considera upgrade del Plan.

500 Internal Server Error

Error inesperado del lado de Cotizave. No es tu culpa.

{
  "code": "internal_error",
  "message": "Ocurrió un error inesperado. Intenta de nuevo."
}

Cómo responder: retry con backoff. Si persiste, revisa la página de status o escríbenos a support@cotizave.com.

502 Bad Gateway

Problema con una fuente upstream (por ejemplo, si Binance o el BCV están caídos). El backend retorna internal_error con HTTP 500 en estos casos, o service_unavailable con 503 si el servicio de datos no está disponible.

{
  "code": "internal_error",
  "message": "An unexpected error occurred."
}

Cómo responder: retry con backoff. Si el error es persistente, revisa la página de status.

503 Service Unavailable

Servicio temporalmente no disponible. Mantenimiento planificado o sobrecarga.

{
  "code": "service_unavailable",
  "message": "Servicio temporalmente no disponible. Intenta de nuevo en unos momentos."
}

Cómo responder: retry con el delay sugerido. Si persiste, revisa la página de status.

Reporte de bugs

Si encuentras un comportamiento que parece un bug, repórtalo a support@cotizave.com con:

• Request exacto que enviaste (sin la API Key)
• Response recibido completo
• Timestamp aproximado del incidente
• Tu email de Cuenta

Respondemos dentro de 24 horas hábiles.