# Errores comunes

> Matriz de referencia para diagnosticar errores de la API y de webhooks.

Referencia rápida de los códigos de error que puede devolver la API, con la causa habitual y la acción recomendada para resolverlos.

## Errores generales

| Código | Descripción | Qué hacer |
|---|---|---|
| `ALREADY_EXISTS` | El recurso que intentas crear ya existe. | Verifica si el recurso ya fue creado antes. Usa una operación de actualización en vez de crear uno nuevo. |
| `EXPIRED_CODE` | El código de acceso o token proporcionado expiró. | Genera un nuevo código o solicita un nuevo enlace antes de reintentar. |
| `INVALID_BODY` | El cuerpo de la petición está mal formado. | Revisa la estructura de tu JSON: que cumpla el esquema esperado y no falte ningún campo requerido. |
| `INVALID_REQUEST` | La petición en general es inválida. | Revisa la URL, los parámetros de consulta y los headers. |
| `RECIPIENT_EXPIRED` | El enlace de firma del destinatario expiró. | Genera y reenvía una nueva invitación a ese destinatario. |
| `LIMIT_EXCEEDED` | Se superó el límite de uso de tu plan. | Revisa los [límites de tu plan](/resources/rate-limits/) o espera al siguiente ciclo de facturación. |
| `NOT_FOUND` | El recurso solicitado no existe (404). | Verifica el ID del recurso (envelope, documento) en la URL, y que no haya sido eliminado. |
| `NOT_IMPLEMENTED` | La función solicitada no está disponible actualmente. | Consulta la documentación para ver los métodos disponibles. |
| `NOT_SETUP` | Falta configuración previa para esta acción. | Completa la configuración necesaria en tu cuenta antes de reintentar. |
| `INVALID_CAPTCHA` | Falló la validación del captcha. | Verifica que el token de captcha se genere y envíe correctamente. |
| `UNAUTHORIZED` | Falta autenticación o es inválida (401). | Verifica que tu API Key sea correcta y esté en el header `Authorization` — ver [Autenticación](/guides/authentication/). |
| `FORBIDDEN` | Acceso denegado al recurso (403). | Verifica que tu API Key tenga los permisos necesarios para esa acción. |
| `UNKNOWN_ERROR` | Error interno inesperado (500). | Reintenta más tarde. Si persiste, contacta a soporte con el payload y la hora del incidente. |
| `RETRY_EXCEPTION` | La operación falló temporalmente pero se puede reintentar. | Implementa reintentos automáticos, idealmente con backoff exponencial. |
| `SCHEMA_FAILED` | Falló la validación estricta del esquema. | Verifica que los tipos de datos enviados coincidan exactamente con la especificación OpenAPI. |
| `TOO_MANY_REQUESTS` | Se excedió el límite de frecuencia (429). | Reduce la frecuencia de tus llamadas — ver [Límites de uso](/resources/rate-limits/). |
| `TWO_FACTOR_AUTH_FAILED` | Falló la verificación de 2FA. | Verifica que el código 2FA sea correcto y no haya expirado. |
| `WEBHOOK_INVALID_REQUEST` | La petición relacionada a un webhook es inválida. | Revisa la configuración de tu endpoint receptor — ver [Webhooks](/guides/webhooks/). |

## Errores de estado del envelope

Ocurren al intentar una acción incompatible con el estado actual del envelope:

| Código | Descripción | Qué hacer |
|---|---|---|
| `ENVELOPE_DRAFT` | La acción no se puede realizar porque el envelope sigue en `DRAFT`. | Distribúyelo primero — ver [Distribuir y la experiencia de firma](/guides/integration-guide/#4-distribuir-y-la-experiencia-de-firma). |
| `ENVELOPE_COMPLETED` | La acción no se puede realizar porque el envelope ya está `COMPLETED`. | No se pueden modificar destinatarios ni campos una vez terminado el proceso de firma. |
| `ENVELOPE_REJECTED` | La acción no se puede realizar porque un destinatario rechazó el envelope. | El flujo de firma queda detenido permanentemente. Crea un nuevo envelope si necesitas reenviar el documento. |
| `ENVELOPE_LEGACY` | El envelope usa un formato obsoleto. | Recréalo con la versión actual de la API para poder interactuar con él. |

---

## Ver también

- [Límites de uso](/resources/rate-limits/) — límites de frecuencia y de plan
- [Webhooks](/guides/webhooks/) — notificaciones de cambios de estado
- [Guía de Integración](/guides/integration-guide/) — flujo general y sus errores frecuentes