Errores comunes

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

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.
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 — límites de frecuencia y de plan
• Webhooks — notificaciones de cambios de estado
• Guía de Integración — flujo general y sus errores frecuentes