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"
  }
}

Idioma de los mensajes

La API habla inglés. Tu integración se apoya en el code; el texto es para que una persona entienda qué pasó.

Si necesitas mostrarle un error a tu usuario final, decide el texto en tu aplicación a partir del code (y de campos estructurados como field cuando vienen), en el idioma de tu producto.

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.

Ejemplo de DEV_FEATURE_RESTRICTED: una key allsign_dev_sk_* pide una función que solo existe con keys live (aquí, firma con e.firma del SAT):

{
  "error": {
    "code": "DEV_FEATURE_RESTRICTED",
    "type": "permission_error",
    "message": "The feature 'fiel_sat' is not available with your current API key (environment: dev).",
    "feature_requested": "fiel_sat",
    "environment": "dev",
    "allowed_features": ["firma_autografa", "firma_simple", "embedded_signing"],
    "allowed_features_display": ["Firma Autógrafa (Wet Signature)", "Firma Simple (Click-to-sign)", "Embedded Signing Widget"],
    "upgrade_message": "This feature is only available with a production key (allsign_live_sk_…). Create a live key in your AllSign dashboard under Developers → API Keys.",
    "upgrade_url": "https://allsign.io/pricing",
    "documentation_url": "https://developers.allsign.io/environments"
  }
}

feature_requested y allowed_features son los códigos estables; allowed_features_display es el nombre comercial de cada función. Con una key trial (TRIAL_FEATURE_RESTRICTED), upgrade_message es "Subscribe to a plan to unlock every feature.".

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. La redacción exacta del mensaje cambia según el endpoint, y algunos 402 traen además los campos required y available. No parsees el texto: usa el code y, si vienen, esos campos.

"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 (100 req/min en los planes de pago, 150 en Business). Algunos endpoints caros tienen además un límite propio. Consulta la página de Rate Limits para la tabla completa, los headers y el patrón de retry recomendado.

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