Errors & Long-Running Operations¶

Polling, operation handles, and the error model.

Long-Running Operations¶

Many platform actions — intake, runs, loads — are asynchronous. Instead of blocking, they return an operation handle you poll to completion.

Polling Pattern¶

sequenceDiagram
    participant C as Your system
    participant P as Platform
    C->>P: createRunRequest
    P-->>C: 202 + operation handle
    loop until terminal
        C->>P: phase1GetJobStatus(handle)
        P-->>C: state (running / completed / failed)
    end

Design your client to be idempotent and to back off between polls. Do not assume a synchronous result from a run-shaped call.

Error Model¶

• Validation errors are returned early (at intake/translation), with the specific issues — see phase1GetArtifactValidationIssues and getTranslationIssues.
• Readiness/approval gates return explicit blocking states, not generic failures.
• Operation failures surface a terminal state on the handle with diagnostic context.

What This Means For Integration¶

• Treat validation and readiness issues as structured, actionable data, not opaque errors.
• Always poll to a terminal state; never assume completion from the initial response.
• Persist operation handles so you can resume tracking after a restart.