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": "participant.email"
  }
}

Códigos de error (E1XXX)

Autenticación (E1000–E1099)

Permisos (E1100–E1199)

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" (E1100)

Tu API key necesita el scope correcto para la operación. Por ejemplo, crear documentos requiere document:write. 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" (E1201)

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 (HTTP 422):

{
  "detail": {
    "success": false,
    "message": "Invalid email format: 'soyisraelortiz.com'. Expected format: user@example.com",
    "validation_errors": [
      {
        "field": "0.email",
        "message": "Invalid email format: 'soyisraelortiz.com'. Expected format: user@example.com",
        "input": "soyisraelortiz.com"
      }
    ]
  }
}

Para errores de entregabilidad (dominio inválido, buzón inexistente):

{
  "detail": {
    "success": false,
    "error_code": "EMAIL_VALIDATION_FAILED",
    "message": "One or more signer email addresses are not valid.",
    "invalid_emails": [
      {
        "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('/v1/documents/create_document', { ... });
  const data = await response.json();

  if (response.status === 422) {
    const detail = data.detail || data;

    // Errores de formato (Pydantic)
    if (detail.validation_errors) {
      detail.validation_errors.forEach(err => {
        showFieldError(err.field, err.message);
      });
      return;
    }

    // Errores de entregabilidad (SendGrid)
    if (detail.invalid_emails) {
      detail.invalid_emails.forEach(err => {
        const msg = err.suggestion
          ? `${err.reason} ${err.suggestion}`
          : err.reason;
        showFieldError(err.email, msg);
      });
      return;
    }

    // Error genérico de validación
    showError(detail.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 (E1500)

La API aplica límites por plan:

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