Errores

Cuando una petición a la API falla, recibirás un código HTTP que indica qué salió mal. Todos los errores v2 usan un formato estandarizado con códigos numéricos para soporte técnico.

Formato de respuesta de error

Todos los errores de la API v2 devuelven un JSON con esta estructura:

{
  "error": {
    "code": "E1200",
    "type": "validation_error",
    "message": "Invalid email format: 'correo-sin-arroba'",
    "field": "participants[0].email"
  }
}

Códigos de error (E1XXX)

Autenticación (E1000–E1099)

Permisos (E1100–E1199)

Los errores de permisos emiten un código string descriptivo, no el numérico. Los E11XX son solo fallbacks por status code y rara vez aparecen en el wire.

Validación (E1200–E1299)

Not Found (E1300–E1399)

Pago / Créditos (E1400–E1499)

Rate Limiting (E1500–E1599)

Conflicto (E1600–E1699)

Bad Request (E1700–E1799)

Internal (E1900–E1999)

Códigos de estado HTTP

Errores comunes y soluciones

"API key no válida" (E1001 / E1002)

# ❌ Incorrecto — falta el prefijo Bearer
curl -H "Authorization: allsign_live_sk_xxx" ...

# ✅ Correcto
curl -H "Authorization: Bearer allsign_live_sk_xxx" ...

"Scope insuficiente" (INSUFFICIENT_SCOPE)

Tu API key necesita el scope correcto para la operación. Por ejemplo, crear documentos requiere document:write. El error 403 incluye error.required_scopes, error.your_scopes y error.hint para que sepas exactamente qué añadir. Genera una nueva key con los scopes necesarios en el Dashboard.

"Créditos insuficientes" (E1400)

{
  "error": {
    "code": "E1400",
    "type": "payment_required",
    "message": "Insufficient credits. Required: 3, Available: 1"
  }
}

Agrega créditos desde el Dashboard antes de reintentar.

"Email de participante no entregable" (EMAIL_VALIDATION_FAILED)

Ocurre cuando uno o más correos en el array participants no pueden recibir mensajes (mailbox inválido, dominio sin MX records, etc.). La validación sucede antes de crear el documento — no habrá registros huérfanos.

AllSign valida emails en dos capas:

Solo los emails con veredicto Invalid son rechazados. Los emails Risky (sospechosos pero posiblemente válidos) se envían con una advertencia interna.

Respuesta de error de formato (HTTP 422):

Los errores de formato (Pydantic) devuelven un único error con el envelope estándar { "error": { ... } } — solo el primer campo inválido, sin array:

{
  "error": {
    "code": "E1200",
    "type": "validation_error",
    "message": "Invalid email format: 'soyisraelortiz.com'. Expected format: user@example.com",
    "field": "participants[0].email"
  }
}

Para errores de entregabilidad (dominio inválido, buzón inexistente), error.details lista cada correo rechazado:

{
  "error": {
    "code": "EMAIL_VALIDATION_FAILED",
    "type": "validation_error",
    "message": "One or more signer email addresses are not valid.",
    "details": [
      {
        "email": "israel@gmail.con",
        "reason": "domain cannot receive email (no MX records)",
        "suggestion": "Did you mean israel@gmail.com?"
      }
    ]
  }
}

Cómo manejar el error en tu código:

try {
  const response = await fetch('/v2/documents', { ... });
  const data = await response.json();

  if (response.status === 422) {
    const err = data.error;

    // Errores de entregabilidad (SendGrid): error.details lista cada correo
    if (err.code === 'EMAIL_VALIDATION_FAILED' && err.details) {
      err.details.forEach(d => {
        const msg = d.suggestion
          ? `${d.reason} ${d.suggestion}`
          : d.reason;
        showFieldError(d.email, msg);
      });
      return;
    }

    // Errores de formato (Pydantic): un solo campo en error.field
    if (err.field) {
      showFieldError(err.field, err.message);
      return;
    }

    // Error genérico de validación
    showError(err.message);
  }
} catch (error) {
  showError('Error de conexión');
}

Cómo resolverlo:

1. Verifica que el correo del participante esté escrito correctamente (sin typos)
2. Confirma con el firmante que su dirección recibe correos externos
3. Si el dominio es corporativo, puede requerir ser whitelisteado — usa WhatsApp como canal alternativo
4. Dominios .xyz, .info o genéricos a menudo tienen filtros estrictos — solicita un correo personal de respaldo

Recomendación UX: Valida el formato del email en tu formulario antes de enviar a la API. Usa un regex como ^[^\s@]+@[^\s@]+\.[^\s@]+$ para atrapar errores obvios y dar retroalimentación instantánea al usuario.

"Documento no encontrado" (E1300)

Verifica que:

1. El document_id sea un UUID válido
2. El documento pertenezca al tenant de tu API key
3. El documento no haya sido eliminado

Rate limiting (RATE_LIMIT_EXCEEDED)

El límite de peticiones está determinado por tu plan de suscripción activo. El default es 100 req/min. Consulta la página de Rate Limits para ver los headers y el patrón de retry recomendado.

Si necesitas más capacidad, contáctanos para un plan personalizado.