Errores

La API responde con un conjunto reducido de estados y cada uno tiene un único significado, de modo que su integración puede decidir qué hacer a partir del código. Esta página describe cada estado, el cuerpo que lo acompaña y por qué un sobre al que la credencial no tiene acceso responde 404.

Códigos de estado

Estado	Significado	Acción
400	Solicitud mal formada o con errores de validación	Compare el cuerpo con el esquema de la referencia de la API; las fechas deben estar en ISO-8601
401	Credenciales rechazadas: sin token, token expirado (un token es válido durante 300 s) o token que el realm no valida	Solicite un token nuevo y revise el prefijo Bearer . Ambos SDKs renuevan el token y reintentan una vez antes de reportar este estado
403	Autenticado, pero la credencial no tiene el permiso de organización	La operación es de administración y solo existe en la interfaz, o el token no incluye bb_sign_org_id. Consulte Autenticación de máquinas
404	El recurso no existe, o pertenece a otra organización o a un espacio de trabajo que la credencial no puede ver. No se distinguen, de forma intencional	Revise el id; si se trata del espacio de trabajo, pida a un administrador que asigne un rol a la credencial en ese espacio
409	El recurso no está en un estado que permita la operación, por ejemplo enviar un sobre ya enviado	Consulte primero el sobre y actúe según su status
422	Una regla de negocio rechazó la solicitud, por ejemplo enviar un sobre sin documento o sin firmante	Corrija el sobre y vuelva a intentarlo
429	Una cuota de la organización está agotada. El cuerpo indica cuál	Pida al administrador de la plataforma que amplíe o renueve la cuota; los SDKs reintentan este estado
0 (solo SDKs)	La solicitud no obtuvo respuesta: no llegó a bb-sign o la respuesta se perdió	En un POST, liste antes de reintentar (ver más abajo)

401 y 403 los genera la cadena de filtros de seguridad y no llevan cuerpo. Los demás errores incluyen un ErrorResponse.

Un 429 indica siempre una cuota agotada; la API no aplica límites de tasa.

Cuerpo del error

{
  "status": 404,
  "error": "Not Found",
  "code": "WORKSPACE_NOT_FOUND",
  "message": "Workspace not found",
  "path": "/api/v1/envelopes",
  "timestamp": "2026-10-10T14:22:31Z",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Campo	Tipo	Siempre presente	Significado
status	entero	sí	El estado HTTP
error	cadena	sí	La frase de razón HTTP
code	cadena	sí	Un código estable para máquinas, como WORKSPACE_NOT_FOUND o NOT_FOUND. Base la lógica en este campo, no en message
message	cadena	sí	Texto para personas; su redacción puede cambiar
path	cadena	sí	La ruta de la solicitud
timestamp	fecha y hora	sí	El momento en que se produjo el error
traceId	cadena	no	Inclúyalo al contactar a soporte; permite ubicar la solicitud en nuestros registros
quota	QuotaViolation	no	Solo en 429

QuotaViolation

{
  "status": 429,
  "error": "Too Many Requests",
  "code": "QUOTA_EXCEEDED",
  "message": "Organization quota exhausted",
  "path": "/api/v1/envelopes",
  "timestamp": "2026-10-10T14:22:31Z",
  "quota": { "dimension": "envelopes", "current": 500, "limit": 500 }
}

Campo	Tipo	Significado
dimension	cadena	La cuota afectada: número de sobres o almacenamiento usado
current	entero	El consumo de la organización al rechazarse la solicitud
limit	entero	El límite de la cuota

El administrador de la plataforma define las cuotas y los administradores de la organización las consultan en la interfaz; consulte Cuotas.

404 en lugar de 403

Aislamiento entre organizaciones

Un sobre o espacio de trabajo que pertenece a otra organización, o que está en un espacio en el que la credencial no tiene rol, responde 404, igual que un id que nunca se emitió. Así, una organización no puede confirmar la existencia de recursos de otra. Dentro de su propia organización, un espacio de trabajo en el que la credencial no puede crear responde 404 WORKSPACE_NOT_FOUND, y los sobres de espacios que no puede leer no aparecen en las listas.

403 se reserva para los rechazos en el nivel de organización: el token no tiene un permiso que la operación requiere, o no incluye el claim de organización.

Errores en los SDKs

Ambos SDKs convierten toda respuesta distinta de 2xx en un único tipo de excepción que contiene el estado y nada más: ni el objeto Response ni los encabezados. Por eso, registrar el error en un log no expone su encabezado Authorization. Los mensajes nunca incluyen su secreto ni su token de acceso, aunque la respuesta de bb-sign los contenga.

	JavaScript	Java
Tipo	BbSignError	BbSignException
Estado	error.statusCode	e.statusCode()
Sin respuesta	statusCode === 0	statusCode() == 0

try {
  await client.envelopes.createEnvelope({ createEnvelopeRequest: request })
} catch (error) {
  if (error.statusCode === 0) {
    // Never reached bb-sign, or the answer was lost. List before you send again.
  }
}

try {
    client.execute(client.envelopes().createEnvelope(request));
} catch (BbSignException e) {
    if (e.statusCode() == 0) {
        // Never reached bb-sign, or the answer was lost. List before you send again.
    }
}

Ninguno de los dos SDKs reintenta un POST cuya respuesta no se recibió: el sobre puede existir ya, y se trata de acuerdos enviados a personas reales. Las solicitudes GET se reintentan ante errores 5xx y fallos de transporte; 429 y 503 se reintentan con cualquier método, porque indican que el servidor no procesó la solicitud. El recorrido completo muestra cómo listar antes de reintentar.