Errores y diagnóstico

Comprueba el estado HTTP antes de interpretar una respuesta. No todas las operaciones devuelven el mismo esquema de error; consulta la operación concreta y evita depender únicamente del texto de un mensaje.

Esta tabla ayuda a diagnosticar respuestas; no afirma que todas las operaciones produzcan cada código.

Causas frecuentesCopiar link al encabezado

• Enviar JSON a /envelope/create o /envelope/use, que requieren multipart.
• Fijar manualmente Content-Type: multipart/form-data sin el límite generado por el cliente.
• Confundir envelopeId con envelopeItemId, o usar texto donde recipientId o fieldId requiere un número.
• Utilizar IDs de una plantilla en un documento creado a partir de ella sin revisar el nuevo recurso.
• Interpretar la versión pending de un PDF como documento final.
• Esperar un objeto pagination cuando la API devuelve sus campos en el nivel superior.

Registros útilesCopiar link al encabezado

Guarda fecha, método, ruta sin secretos, estado HTTP y el ID local del proceso. Sanitiza el cuerpo antes de registrarlo. Una respuesta puede incluir correos, tokens o datos personales.

Si una creación o distribución vence por tiempo de espera, consulta el recurso antes de repetirla. externalId facilita relacionar datos, pero no hay una garantía documentada de idempotencia ni un encabezado de deduplicación en esta referencia.

Maneja errores en TypeScriptCopiar link al encabezado

Comprueba response.ok antes de consumir datos del recurso. Este helper local conserva el estado HTTP y lee un mensaje solo si existe; no presupone un formato de error uniforme.

class DigitoApiError extends Error {
  readonly status: number;
  constructor(status: number, message: string) {
    super(message);
    this.status = status;
    this.name = 'DigitoApiError';
  }
}

async function readJson<T>(response: Response): Promise<T> {
  if (response.ok) return (await response.json()) as T;

  let message = `Solicitud fallida: HTTP ${response.status}`;
  if ((response.headers.get('content-type') ?? '').includes('application/json')) {
    const body: unknown = await response.json().catch(() => null);
    if (body && typeof body === 'object' && 'message' in body && typeof body.message === 'string') {
      message = body.message;
    }
  }

  throw new DigitoApiError(response.status, message);
}

const token = process.env.DIGITO_API_TOKEN;
if (!token) throw new Error('Falta DIGITO_API_TOKEN');

try {
  const response = await fetch(
    'https://business.digito.do/api/v2/envelope?perPage=1',
    {
      headers: { Authorization: token },
      signal: AbortSignal.timeout(15_000),
    }
  );

  const result = await readJson<{ data: Array<{ id: string }> }>(response);

  console.log(result.data.map(({ id }) => id));
} catch (error) {
  if (error instanceof DigitoApiError) {
    // Guarda solo metadatos seguros; no registres el cuerpo de error ni la clave.
    console.error('Estado HTTP:', error.status);

    if (error.status === 401) console.error('Revisa la clave configurada en el servidor');

    if (error.status === 429) console.error('Espacia las lecturas y respeta Retry-After');
  } else {
    console.error('La lectura no se completó por un error de red o de procesamiento');
  }
}

DigitoApiError y readJson son helpers de tu aplicación, no exports de un SDK. Los tipos de respuesta locales describen lo que consume el ejemplo y no validan el JSON en ejecución.

Comprueba el estado con cURLCopiar link al encabezado

curl --silent --show-error --fail-with-body \
  'https://business.digito.do/api/v2/envelope?perPage=1' \
  -H "Authorization: $DIGITO_API_TOKEN" \
  --write-out '\nEstado HTTP: %{http_code}\n'

--fail-with-body conserva el cuerpo para diagnóstico y devuelve un código de salida de error ante respuestas HTTP fallidas. No copies cuerpos con datos personales a registros compartidos. Para automatizar lecturas temporales, usa paginación y reintentos.