> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Manejo de errores

> Sobre de respuesta de GOWA, códigos de error y estados HTTP, y cómo manejarlos.

## Respuesta sobre

Cada respuesta JSON tiene la misma forma:

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Success",
  "results": { }
}
```

| Campo | Descripción |
| - | - |
| `code` | `SUCCESS` o un código de error. Utilice esto, junto con el estado HTTP, para ramificar. |
| `message` | Detalles legibles para el ser humano. |
| `results` | Carga útil con éxito. Generalmente omitido en errores. |

## Código de error

| Código | HTTP | Comenzando | Qué hacer |
| - | - | - | - |
| `VALIDATION_ERROR` | 400 | Falta o no es válido el campo. El nombre del `message`. | Corregir la solicitud. |
| `INVALID_JID` | 400 | El número no está en WhatsApp, o el JID está mal formado. | Compruebe el número; no vuelva a intentarlo. |
| `ALREADY_LOGGED_IN` | 400 | Inicio de sesión solicitado para un dispositivo que ya está conectado. | Nada o cierre la sesión primero. |
| `DEVICE_ID_REQUIRED` | 400 | Ningún dispositivo dado y el servidor tiene cero o varios dispositivos. | Enviar `X-Device-Id`. |
| `AUTHENTICATION_ERROR` | 401 | El dispositivo no está conectado a WhatsApp (o la autenticación de WhatsApp falló). | Comprueba `/devices/{id}/status`; empareja de nuevo si es necesario. |
| `NOT_FOUND` | 404 | Recurso no encontrado (mensaje, chat, programación…). | Compruebe el ID. |
| `DEVICE_NOT_FOUND` | 404 | `X-Device-Id` nombra un dispositivo desconocido. | Compruebe el ID de la ranura o JID. |
| `AVATAR_HIDDEN` | 403 | La imagen de perfil está oculta por la configuración de privacidad. | No trate esto como una ausencia confirmada o elimine una imagen cacheada únicamente sobre este resultado. |
| `AVATAR_NOT_SET` | 404 | El contacto no tiene imagen de perfil. | Borrar una imagen en caché sólo después de comprobar este código, no cualquier 404. |
| `CROSS_SITE_REQUEST_BLOCKED` | 403 | El origen del navegador no es de confianza. | Serva el panel de control sobre HTTP(S) y configure el origen exacto de confianza. |
| `CONTEXT_ERROR` | 408 | La operación fue cancelada o agotada internamente. | Reintentar una vez. |
| `WA_REACHOUT_TIMELOCK` | 429 | WhatsApp bloquea temporalmente nuevos chats de esta cuenta. | Detener la extensión; ver [Enviando límites](https://gowa-docs.mintlify.site/es/advanced/rate-limiting.md). |
| `INTERNAL_SERVER_ERROR` | 500 | Fallo inesperado, incluido el pánico recuperado. | Reintentar con backoff; comprobar los registros. |
| `QR_CHANNEL_ERROR` | 500 | No se pudo obtener un código QR. | Reintentar inicio de sesión. |
| `SESSION_SAVED_ERROR` | 500 | No se pudo persistir en la sesión. | Comprobar almacenamiento y permisos. |
| `UPLOAD_MEDIA_ERROR` | 500 | La subida de medios a WhatsApp falló. | Reintentar; compruebe el tamaño y el formato. |
| `WEBHOOK_ERROR` | 500 | Configuración de Webhook o error de entrega. | Compruebe la URL del webhook. |
| `INVALID_WA_CLI` | 500 | El cliente WhatsApp del dispositivo no está inicializado. | Volver a conectar o iniciar sesión. |
| `DEVICE_MANAGER_UNAVAILABLE` | 503 | El gestor de dispositivos no está inicializado. | Vuelva a intentarlo pronto; compruebe los registros de inicio. |
| `GATEWAY_TIMEOUT` | 504 | La solicitud superó los 45 segundos. | La acción aún puede completarse; compruebe antes de reintentar. |

Los fallos básicos de Auth devuelven `401` de la capa de autenticación antes de llegar a los manejadores de GOWA; trata cualquier `401` sin un `code` de GOWA como credenciales erróneas.

## Reintentando de forma segura

Enviar no es **idempotente**: GOWA no tiene clave de idem. Si un tiempo de envío (`504`, error de red), el mensaje ya puede ser entregado. Antes de reenviar, comprueba el chat con `GET /chat/{chat_jid}/messages?is_from_me=true&limit=5`, o acepta el riesgo de un duplicado.

| Reintentar | No reintentar |
| - | - |
| `500 INTERNAL_SERVER_ERROR`, `UPLOAD_MEDIA_ERROR`, `CONTEXT_ERROR`, `503` | `400` errores, `INVALID_JID`, `404`, `401`, `WA_REACHOUT_TIMELOCK` |

Usa un retroceso exponencial con un límite máximo y limita los intentos.

```javascript theme={null}
async function gowa(path, body, attempt = 1) {
  const res = await fetch(`http://localhost:3000${path}`, {
    method: "POST",
    headers: {
      Authorization: "Basic " + Buffer.from("admin:changeme").toString("base64"),
      "Content-Type": "application/json",
      "X-Device-Id": "my-device",
    },
    body: JSON.stringify(body),
  });
  const data = await res.json().catch(() => ({}));
  if (res.ok) return data.results;

  const retryable = [500, 503].includes(res.status) && data.code !== "INVALID_JID";
  if (retryable && attempt < 4) {
    await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
    return gowa(path, body, attempt + 1);
  }
  throw Object.assign(new Error(data.message || res.statusText), { code: data.code, status: res.status });
}
```

## Depuración

* Ejecuta con `APP_DEBUG=true` para registros detallados.
* Compruebe el dispositivo: `GET /devices/{device_id}/status` (`is_connected`, `is_logged_in`).
* `GET /health` sólo confirma que el proceso y la base de datos están activos; no verifica la conectividad de WhatsApp.


## Related topics

- [Manejo de medios](https://gowa-docs.mintlify.site/es/examples/media-handling.md)
- [Selección de dispositivo y dispositivo múltiple](https://gowa-docs.mintlify.site/es/concepts/multidevice.md)
- [Errores](https://gowa-docs.mintlify.site/es/api-reference/errors.md)
- [Integración de Chatwoot](https://gowa-docs.mintlify.site/es/integrations/chatwoot.md)
- [Enviando mensajes](https://gowa-docs.mintlify.site/es/examples/sending-messages.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.