API - Errores de integracion

Esta pagina resume los errores que Business Central debe contemplar durante la integracion.

Regla general

• todas las respuestas de error incluyen traceId
• guarda siempre traceId, requestId y externalRef en los logs de BC
• no reintentes a ciegas errores de validacion o estado

Envelope de error

{
  "code": "INVALID_STATE",
  "message": "The request is already signed.",
  "traceId": "00-abc123...",
  "details": null
}

Errores principales

HTTP	code	Causa habitual	Que debe hacer BC
400	INVALID_INPUT	falta un campo, formato incorrecto	corregir payload y reenviar
401	UNAUTHENTICATED	bearer token ausente o invalido	revisar BC_BEARER_TOKEN
403	FORBIDDEN	codigo de activacion invalido o expirado	emitir un nuevo codigo
404	NOT_FOUND	deviceId o requestId inexistente	validar identificadores antes de continuar
409	INVALID_STATE	la solicitud ya no admite esa operacion	refrescar estado y adaptar el flujo
413	PDF_TOO_LARGE	PDF supera MAX_PDF_MB	reducir tamano del PDF
422	PDF_INVALID	Base64 o contenido PDF invalido	regenerar PDF o revisar codificacion
429	TOO_MANY_REQUESTS	limite temporal o abuso	esperar y reintentar con backoff
500	INTERNAL_ERROR	error inesperado	registrar traceId y escalar

Reintentos recomendados

Reintentar con backoff

• fallos temporales de red desde BC
• 429 TOO_MANY_REQUESTS
• 5xx puntuales

No reintentar sin corregir antes

• 400 INVALID_INPUT
• 401 UNAUTHENTICATED
• 404 NOT_FOUND
• 409 INVALID_STATE
• 413 PDF_TOO_LARGE
• 422 PDF_INVALID

Casos tipicos

401 UNAUTHENTICATED

Revisa: - cabecera Authorization - formato Bearer <token> - valor real de BC_BEARER_TOKEN en la API

409 INVALID_STATE

Suele ocurrir cuando: - la solicitud ya fue firmada - la solicitud se cancelo - la solicitud expiro

Accion recomendada: - llamar a GET /v1/signature-requests/{requestId} - persistir el estado devuelto en BC

413 PDF_TOO_LARGE

Accion recomendada: - reducir resolucion o peso del PDF antes de enviarlo - evitar PDFs escaneados innecesariamente grandes

500 INTERNAL_ERROR

Accion recomendada: - guardar traceId - volver a consultar estado si existe requestId - escalar con traceId y hora aproximada del error