API / Errores

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:

error schema

{ "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

Código	Significado	Ejemplos
200	OK	Request exitoso
400	Bad Request	Parámetros inválidos o mal formateados
401	Unauthorized	API Key faltante o inválida
403	Forbidden	Plan insuficiente, key de ambiente incorrecto
404	Not Found	Recurso inexistente (ej: market desconocido)
422	Unprocessable Entity	Parámetros válidos en formato pero lógicamente incorrectos
429	Too Many Requests	Rate limit excedido
500	Internal Server Error	Error interno de Cotizave
502	Bad Gateway	Problema con una fuente upstream
503	Service Unavailable	Mantenimiento o sobrecarga temporal

Errores comunes

400 Bad Request

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

response

{ "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.

response

{ "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.

response

{ "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.

response

{ "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).

response

{ "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.

response

{ "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.

response

{ "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.

response

{ "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.

response

{ "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.

← AnteriorRate limits Siguiente →Endpoints