Errores de API y reintentos
Respuestas de error estructuradas, idempotencia y recuperación del procesamiento asincrónico.
Fallos HTTP predecibles#
401/403 indica fallo de autenticación o autorización. 404 oculta objetos inaccesibles. 409 señala configuraciones inmutables, cargas ya utilizadas o estado de tarea inválido. 413 aplica límites de tamaño, 422 valida la configuración, y 429 está limitando la velocidad/concurrencia.
Los fallos transitorios de servicio comercial o cola devuelven 503. Reintente el procesamiento con el mismo ID de tarea y opciones idénticas, usando retroceso exponencial y un presupuesto de reintentos limitado.
Ejemplo de recuperación#
# Safe repeated processing attempt for the SAME task and options
curl -X POST https://api.pdfhq.io/v1/tasks/TASK_ID/process \
-H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
-d '{"options":{"compression_level":"recommended"}}'Una tarea de procesamiento fallida no se puede revertir simplemente eliminando la tarea. Consulte el uso de la cuenta y el soporte al investigar discrepancias de liquidación.
