Errores y recuperación
Conserva código HTTP, code, traceId, hora e identificadores de negocio. La API añade X-Trace-Id a sus respuestas; los errores de aplicación lo repiten en el cuerpo. Un error de proxy o formato puede no tener este JSON.
{
"code": "INVALID_STATE",
"message": "Request is not in displayed state.",
"traceId": "identificador-de-la-llamada",
"details": null
}
No registres bearer, token tablet, PFX, contraseñas ni documentos Base64.
Errores comunes
| HTTP / código | Significado | Acción |
|---|---|---|
400 INVALID_INPUT |
Campo ausente o formato inválido | Corregir entrada |
401 UNAUTHENTICATED |
Bearer BC incorrecto/ausente, o token tablet ausente | Revisar cabecera y configuración |
403 FORBIDDEN |
Token tablet inválido/ajeno, o activación incorrecta/caducada | Revisar dispositivo; reactivar si procede |
404 NOT_FOUND |
Recurso inexistente o archivo manuscrito ausente | Revisar ID, retención y storage |
409 INVALID_STATE |
Operación incompatible con estado | Consultar estado actual |
409 CONFLICT |
Conflicto operativo o idempotencia/concurrencia | Resolver según la operación |
413 PDF_TOO_LARGE |
Bytes PDF por encima de MAX_PDF_MB |
Reducir documento |
422 PDF_INVALID |
Base64/PDF no válido | Regenerar/corregir PDF |
429 TOO_MANY_REQUESTS |
Rate limit de activación | Esperar y aplicar backoff |
500 INTERNAL_ERROR |
Error inesperado | Consultar estado y escalar con trace |
503 SERVICE_UNAVAILABLE |
Dependencia o cola no disponible | Revisar salud/logs |
PAdES
| HTTP / código | Acción |
|---|---|
409 CONFLICT |
Consultar estado; conservar misma clave/payload/firma si es reintento; no reutilizarla para otro documento |
410 SIGNATURE_REQUEST_EXPIRED |
Crear una operación nueva si aún se necesita firma |
410 SIGNED_RESULT_PURGED |
Buscar copia archivada; una nueva firma es otra operación de negocio |
422 CERTIFICATE_INVALID |
Revisar vigencia, RSA, uso de clave y formato DER público |
422 CERTIFICATE_CHAIN_INVALID |
Revisar emisores ajenos/falsificados, vigencia/restricciones de CA, AIA inaccesible o malformado y límites de resolución/espacio CMS; el error puede ocurrir aun omitiendo certificateChainBase64 |
422 PDF_UNSUPPORTED |
Revisar cifrado, firmas previas o compatibilidad PDF |
422 SIGNATURE_INVALID |
Firmar bytes DER exactos; comprobar algoritmo y certificado |
422 SIGNED_PDF_CORRUPT |
Revisar pérdida/modificación de archivo; no confundir con purga legítima |
La extensión AL muestra HTTP y OperationId, sin exponer el cuerpo de error. Usa esa referencia para localizar la operación en el backend. La configuración de permisos/certificado se comprueba también localmente en BC.
Si el emisor no publica AIA accesible, el operador puede añadir sus certificados públicos al catálogo del servidor; configuración de emisores. Para UANATACA CA1 2021, el catálogo viene incluido: confirma primero que la API ejecuta 0.2.14 o posterior y que estás creando una operación nueva.
Avisos de confianza en el lector
Un resultado signed confirma que la API aceptó y publicó el PDF; no afirma que Adobe u otro lector confíe en el certificado. Una cadena completa no crea una autoridad de confianza en el equipo del lector. Comprueba los detalles de validación del lector para distinguir falta de confianza, revocación no comprobable y alteración de la firma.
Tras actualizar la API, genera una firma nueva desde el PDF original con un OperationId nuevo para incorporar los intermedios. Volver a descargar un resultado anterior conserva sus bytes. El servicio mantiene B-B: no incorpora TSA, evidencia OCSP/CRL ni B-T/LT/LTA. No debe presentarse la resolución de emisores como garantía de un indicador de confianza en todos los lectores.
OCR
429 OCR_QUEUE_FULL incluye Retry-After. Espera antes de encolar de nuevo. Si el trabajo terminó en failed, lee errorCode: puede ser PDF_INVALID, OCR_TIMEOUT, OCR_CANCELLED u OCR_FAILED.
Un job perdido tras reinicio/retención devuelve 404; reenviarlo genera otro trabajo.
Reintentar con criterio
Las lecturas pueden reintentarse con backoff ante fallo temporal. PAdES permite recuperar usando la misma clave y datos; consulta primero si existe una operación.
La creación manuscrita y OCR no son idempotentes. Una respuesta perdida no significa que no se crearon: reconciliar primero evita duplicados. Tras una subida manuscrita perdida, consulta el estado; signed indica que el resultado ya se aceptó y no debe sobrescribirse.
En gestión de tablet, DELETE con 409 exige resolver solicitudes pending, displayed o signing. deactivate con 409 exige cerrar el activo. Revocar corta el acceso, pero no cancela las solicitudes.
Continúa con Estados manuscritos, Protocolo PAdES o Operación de tablets.