Códigos de error y referencia de estado

Guía completa de códigos de error de Smart Money API, códigos de estado HTTP y pasos para solucionar problemas. Comprende las respuestas de error y resuelve problemas de integración rápidamente.

Códigos de éxito 2xx

Las respuestas de éxito indican que la solicitud se procesó correctamente.

Código	Estado	Significado
200	OK	Solicitud exitosa. El cuerpo de la respuesta contiene los datos solicitados.
201	Created	Recurso creado exitosamente. La respuesta incluye el nuevo recurso.
204	No Content	Solicitud exitosa pero no hay contenido para devolver (ej., DELETE).

Ejemplo de respuesta 200

JSON

{
  "success": true,
  "data": {
    "total": 42,
    "positions": [...],
    "pagination": {
      "page": 1,
      "limit": 50
    }
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Códigos de error del cliente 4xx

Los errores del cliente indican que la solicitud estaba malformada o era inválida. Corrige tu solicitud y vuelve a intentarlo.

Código	Estado	Causa
400	Bad Request	Sintaxis de solicitud malformada. Verifica los parámetros de consulta, encabezados y cuerpo de la solicitud.
401	Unauthorized	Credenciales de autenticación faltantes o inválidas. Verifica tu clave API o token JWT.
402	Payment Required	El pago de tu suscripción falló. Actualiza la información de facturación en tu cuenta.
403	Forbidden	Autenticado pero no autorizado para este recurso. Tu plan no incluye esta función.
404	Not Found	El recurso no existe. Verifica la URL del endpoint y los parámetros.
429	Too Many Requests	Límite de tasa excedido. Espera antes de reintentar. Verifica el encabezado Retry-After.
422	Unprocessable Entity	Validación fallida. Los parámetros de la solicitud son inválidos o faltan campos obligatorios.

Ejemplos de errores de autenticación

Clave API faltante (401)

JSON

{
  "success": false,
  "error": {
    "code": "AUTH_MISSING_KEY",
    "message": "No se proporcionaron credenciales de autenticación.",
    "resolution": "Incluye tu clave API en el encabezado Authorization: Authorization: Bearer sk_live_..."
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Clave API inválida (401)

JSON

{
  "success": false,
  "error": {
    "code": "AUTH_INVALID_KEY",
    "message": "Clave API inválida o expirada.",
    "resolution": "Genera una nueva clave API desde tu consola en https://smartmoneyapi.com/console"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Límite de tasa (429)

Cuando excedes tu cuota de API, el servidor devuelve 429 Too Many Requests. Verifica los encabezados de respuesta para obtener información sobre el límite de tasa:

Encabezados HTTP

X-Requests-Remaining: 0
X-Requests-Limit: 200
X-Requests-Reset: 1711116922
Retry-After: 3600

Respuesta de error por límite de tasa

JSON

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Límite diario de solicitudes API (10) excedido.",
    "resolution": "Actualiza al plan Trader ($29/mes, 400 solicitudes/día) o Pro ($79/mes, 4,000 solicitudes/día).",
    "reset_at": "2026-03-22T09:00:00Z"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Errores de validación (422)

Los errores de validación ocurren cuando los parámetros de tu solicitud son inválidos o faltan campos obligatorios.

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Falló la validación de la solicitud.",
    "details": [
      {
        "field": "symbol",
        "error": "Par de trading inválido. Formato esperado: BTCUSDT"
      },
      {
        "field": "min_position_size",
        "error": "Debe ser un número positivo"
      }
    ],
    "resolution": "Corrige los errores de validación y vuelve a intentarlo."
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Códigos de error del servidor 5xx

Los errores del servidor indican un problema de nuestro lado. Son temporales y generalmente se resuelven rápidamente. Implementa lógica de reintento con retroceso exponencial.

Código	Estado	Acción
500	Internal Error	Error inesperado del servidor. Reintenta con retroceso exponencial.
502	Bad Gateway	Interrupción temporal del servicio. Reintenta después de unos segundos.
503	Service Unavailable	Mantenimiento o interrupción temporal. Consulta la página de estado. Reintenta después del intervalo Retry-After.
504	Gateway Timeout	La solicitud tardó demasiado. El servidor pudo haberla procesado de todos modos. Verifica la idempotencia.

Ejemplo de error del servidor (503)

JSON

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Servicio temporalmente no disponible por mantenimiento.",
    "resolution": "Por favor, reintenta después de 5 minutos. Consulta el estado en https://status.smartmoneyapi.com"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Guía de solución de problemas

401 No autorizado - Clave API inválida

Problema: Recibes errores 401 incluso con una clave API.

Soluciones:

Verifica que la clave API esté incluida en el encabezado Authorization con el prefijo "Bearer"
Comprueba que tu clave API no haya expirado o sido revocada
Asegúrate de estar usando la clave correcta (producción, staging o desarrollo)
Genera una nueva clave API desde tu consola si la actual está perdida

403 Prohibido - Función no disponible

Problema: Recibes errores 403 en ciertos endpoints.

Soluciones:

Verifica tu nivel de API. Algunos endpoints requieren planes Trader o Pro
Actualiza tu plan en /pricing.html para acceder a funciones premium
Confirma que la clave API tenga los scopes requeridos habilitados
Contacta al soporte si crees que deberías tener acceso

429 Demasiadas solicitudes - Límite de tasa

Problema: Recibes errores 429 y límite de tasa.

Soluciones:

Implementa lógica de reintento con retroceso exponencial (espera 1s, 2s, 4s, etc.)
Almacena en caché las respuestas para evitar llamadas API redundantes
Usa WebSocket para datos en tiempo real en lugar de sondear endpoints REST
Actualiza tu plan para obtener cuotas más altas (Trader 1,000/día, Pro 5,000/día)
Agrupa múltiples consultas en solicitudes únicas cuando sea posible

400 Solicitud incorrecta - Parámetros inválidos

Problema: Recibes errores 400 con solicitudes malformadas.

Soluciones:

Consulta la documentación de la API para ver parámetros obligatorios y opcionales
Verifica los tipos de parámetros (strings vs números, arrays vs objetos)
Asegúrate de que el JSON sea válido y esté correctamente formateado
Usa URLs de endpoints correctas con parámetros de ruta apropiados
Verifica errores tipográficos en los nombres de los parámetros de la consulta

Errores del servidor 5xx - Interrupciones temporales

Problema: Recibiendo errores 500, 502, 503 o 504.

Soluciones:

Verifica el estado del servicio en https://status.smartmoneyapi.com
Implementa reintentos automáticos con retroceso exponencial (máximo 5-10 intentos)
Espera 30-60 segundos antes de reintentar errores 503
Usa el encabezado Retry-After para determinar el tiempo de reintento
Suscríbete a la página de estado para recibir notificaciones de incidentes

Formato de respuesta de error

Todas las respuestas de error siguen un formato consistente:

JSON

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Mensaje de error legible",
    "details": {...},
    "resolution": "Pasos para resolver el problema"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

¿Necesitas más ayuda?

Consulta nuestra documentación de la API o contacta al soporte con tu código de error y detalles de la solicitud.

Referencia de la API

Obtén soporte

¿Tienes preguntas? Consulta nuestra documentación o contacta al soporte.

Abrir consola