Cancel a translation job

POST/v1/public/document-translator/jobs/{jobId}/cancel

translator:cancelscope ដែលត្រូវការ

Refunds the prepaid debit by the §3.5 rule: full within 60 s of acceptance; `tierPrice × (1 - pagesDone/pagesTotal)` while `uploading`…`translating`; nothing once `rendering` — a finished job answers `409 job_already_done`. Requires scope `translator:cancel` (10/min per key).

Parameters

Name	In	ចាំបាច់	ការពិពណ៌នា
jobId	path	✓	The job id returned by `POST /jobs` (uuidv7).e.g. 019a2c3d-4e5f-7a9b-8c0d-1e2f3a4b5c6d

ចម្លើយកំហុស

200Job cancelled — credits refunded per the rule.

application/json

{
  "state": "cancelled",
  "refundedCredits": 999
}

400Malformed request — missing field or bad value.

application/json

{
  "error": "invalid_request",
  "message": "`jobId` must be a UUID.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c"
}

401Missing or unrecognised API key.

application/json

{
  "error": "missing_authorization",
  "message": "Send `Authorization: Bearer <api-key>`.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c"
}

403The key is valid but lacks the scope this operation requires.

application/json

{
  "error": "scope_missing",
  "message": "This key lacks the required scope.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c",
  "requiredScope": "translator:read"
}

404The job does not exist — or exists under a different API key. Ownership misses deliberately return 404 (never 403) so job existence cannot be probed.

application/json

{
  "error": "job_not_found",
  "message": "No such job.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c"
}

409The job already reached `rendering` or a terminal state — it cannot be cancelled and is not refunded.

application/json

{
  "error": "job_already_done",
  "message": "The job is already finished — it cannot be cancelled.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c",
  "state": "done"
}

429Per-key or per-account rate limit exhausted. Retry after the `Retry-After` interval (see the rate-limit table).

application/json

{
  "error": "rate_limited",
  "message": "Rate limit exhausted — retry after the interval.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c",
  "retryAfter": 42
}

500Engine failure — the wallet debit is refunded when one was taken.

application/json

{
  "error": "internal_error",
  "message": "Something went wrong — retry shortly.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c"
}

503A required upstream (OpenRouter, Bayla, key verification) is unavailable — the wallet debit is refunded when one was taken.

application/json

{
  "error": "upstream_unavailable",
  "message": "A required upstream is unavailable — retry shortly.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c"
}