GET /jobs/

Cuando el sistema está al máximo de capacidad, cualquier endpoint de conversión (/convert, /convert/raw, /convert/from-url, /convert/stream, /convert/stream-from-url, /convert/accelerated) puede devolver 202 Accepted en lugar de 200. Esto significa que tu petición fue aceptada y encolada para procesarse en cuanto haya capacidad. La respuesta 202 incluye un job_id y una URL para consultar el estado:

{
  "accepted": true,
  "auto_async": true,
  "job_id": "a1b2c3d4-e5f6-...",
  "status": "queued",
  "status_url": "/jobs/a1b2c3d4-e5f6-...",
  "retry_after_seconds": 5,
  "message": "All backends are at capacity. Your request has been queued..."
}

Consultar el estado

GET /jobs/{job_id}
x-api-key: TU_API_KEY

Respuestas posibles

queued
processing
completed
failed

El job está en cola, esperando un backend libre.

{
  "job_id": "a1b2c3d4-...",
  "status": "queued",
  "created_at": 1719763200000
}

Un backend está procesando la conversión.

{
  "job_id": "a1b2c3d4-...",
  "status": "processing",
  "started_at": 1719763205000
}

La conversión terminó. El campo body contiene el resultado (Markdown o JSON según los parámetros originales).

{
  "job_id": "a1b2c3d4-...",
  "status": "completed",
  "http_status": 200,
  "headers": { "content-type": "text/markdown; charset=utf-8" },
  "body": "# Mi documento\n\nContenido convertido...",
  "completed_at": 1719763210000
}

La conversión falló tras varios reintentos.

{
  "job_id": "a1b2c3d4-...",
  "status": "failed",
  "error": "All backends returned 503",
  "failed_at": 1719763220000
}

Polling recomendado

Recibe 202 → espera retry_after_seconds (5s por defecto).
Llama GET /jobs/{job_id}.
Si status es queued o processing, espera 5s y repite.
Si status es completed, usa body como resultado.
Si status es failed, reintenta la conversión original con backoff.

import requests, time

r = requests.post("https://api.markpdf.tech/convert/raw",
    headers={"x-api-key": "TU_KEY", "content-type": "application/pdf"},
    data=pdf_bytes)

if r.status_code == 202:
    job = r.json()
    while True:
        time.sleep(job.get("retry_after_seconds", 5))
        status = requests.get(
            f"https://api.markpdf.tech/jobs/{job['job_id']}",
            headers={"x-api-key": "TU_KEY"}
        ).json()
        if status["status"] == "completed":
            markdown = status["body"]
            break
        if status["status"] == "failed":
            raise Exception(status["error"])
else:
    markdown = r.text

const res = await fetch("https://api.markpdf.tech/convert/raw", {
  method: "POST",
  headers: { "x-api-key": "TU_KEY", "content-type": "application/pdf" },
  body: pdfBuffer,
});

if (res.status === 202) {
  const job = await res.json();
  let status;
  do {
    await new Promise(r => setTimeout(r, (job.retry_after_seconds || 5) * 1000));
    const poll = await fetch(`https://api.markpdf.tech/jobs/${job.job_id}`, {
      headers: { "x-api-key": "TU_KEY" },
    });
    status = await poll.json();
  } while (status.status === "queued" || status.status === "processing");

  if (status.status === "completed") {
    const markdown = status.body;
  } else {
    throw new Error(status.error);
  }
} else {
  const markdown = await res.text();
}

Los resultados de jobs completados se mantienen disponibles aproximadamente 1 hora. Después pueden expirar. Si recibes 404 al consultar un job, reenvía la conversión.

El 202 es automático y transparente — no necesitas activarlo. Solo ocurre cuando todos los backends están saturados. En condiciones normales, siempre recibirás 200 directamente.

Referencia

GET /jobs/{id}

GET /jobs/

Consultar el estado

Respuestas posibles

Polling recomendado

​GET /jobs/

​Consultar el estado

​Respuestas posibles

​Polling recomendado

GET /jobs/

Consultar el estado

Respuestas posibles

Polling recomendado