Gestión de errores

La API de Meirra usa los códigos de estado HTTP convencionales para indicar el éxito o fallo de las solicitudes. En general: • **2xx** - Éxito. La solicitud funcionó como se esperaba. • **4xx** - Error de cliente. La solicitud no es válida o no puede atenderse. • **5xx** - Error de servidor. Algo ha fallado por nuestra parte. Todas las respuestas de error usan una estructura JSON consistente con un código, un mensaje y los detalles necesarios para diagnosticar y manejar el problema.

Todos los errores siguen un formato consistente: ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Descripción legible del error", "details": { ... } } } ``` El campo `code` es un código legible por máquina que puedes usar en tu lógica de manejo de errores. El `message` ofrece una descripción para personas. El objeto opcional `details` aporta contexto adicional según el tipo de error.

Los errores de autenticación ocurren cuando tu clave de API falta, no es válida o no tiene permiso. | Código | HTTP | Descripción | |--------|------|-------------| | `INVALID_API_KEY` | 401 | La clave de API falta o no es válida | | `API_KEY_REVOKED` | 401 | La clave de API ha sido revocada | | `IP_NOT_ALLOWED` | 403 | La IP de la solicitud no está en la lista permitida | **Ejemplo:** ```json { "success": false, "error": { "code": "INVALID_API_KEY", "message": "La clave de API proporcionada no es válida o falta" } } ``` **Cómo solucionarlo:** Verifica que la clave de API es correcta y se incluye en la cabecera `x-api-key`. Comprueba si la clave ha sido revocada en el Panel de Desarrollador.

Los errores de saldo ocurren cuando tu cuenta no tiene créditos suficientes para la solicitud. | Código | HTTP | Descripción | |--------|------|-------------| | `INSUFFICIENT_BALANCE` | 402 | Saldo insuficiente para la solicitud | **Ejemplo:** ```json { "success": false, "error": { "code": "INSUFFICIENT_BALANCE", "message": "Tu saldo de $0.50 es insuficiente para esta solicitud (se requieren $1.00)", "details": { "balanceRemaining": 0.50, "costRequired": 1.00 } } } ``` **Cómo solucionarlo:** Recarga el saldo de tu cuenta desde el Panel de Desarrollador. Considera configurar avisos de saldo bajo para evitar interrupciones.

Los errores de límite de uso ocurren cuando superas la tasa de solicitudes permitida. | Código | HTTP | Descripción | |--------|------|-------------| | `RATE_LIMIT_EXCEEDED` | 429 | Demasiadas solicitudes | **Ejemplo:** ```json { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Límite de uso superado. Reintenta en 60 segundos.", "details": { "limit": 1000, "remaining": 0, "resetAt": "2026-02-27T15:30:00Z", "retryAfter": 60 } } } ``` **Cómo solucionarlo:** Implementa retroceso exponencial. Consulta la cabecera `Retry-After` para saber cuándo reintentar. Considera distribuir las solicitudes en el tiempo.

Los errores de validación ocurren cuando los parámetros de la solicitud faltan o no son válidos. | Código | HTTP | Descripción | |--------|------|-------------| | `INVALID_REQUEST` | 400 | Parámetros faltantes o no válidos | | `INVALID_EMAIL` | 400 | Formato de email no válido | | `BATCH_TOO_LARGE` | 400 | El lote supera el tamaño máximo | **Ejemplo:** ```json { "success": false, "error": { "code": "INVALID_REQUEST", "message": "La validación de la solicitud ha fallado", "details": { "field": "email", "issue": "El email es obligatorio" } } } ``` **Cómo solucionarlo:** Revisa el campo `details` para conocer el fallo concreto de validación. Asegúrate de proporcionar todos los campos requeridos en el formato esperado.

Los errores de servicio ocurren cuando algo falla en nuestra infraestructura. | Código | HTTP | Descripción | |--------|------|-------------| | `SERVICE_ERROR` | 500 | Fallo interno del servicio | | `SERVICE_UNAVAILABLE` | 503 | Servicio temporalmente no disponible | | `UPSTREAM_ERROR` | 502 | Una dependencia externa ha fallado | **Ejemplo:** ```json { "success": false, "error": { "code": "SERVICE_ERROR", "message": "Se ha producido un error interno. Inténtalo de nuevo más tarde." } } ``` **Cómo solucionarlo:** Son errores transitorios. Implementa lógica de reintentos con retroceso exponencial. Si los errores persisten, revisa la página de estado o contacta con soporte.