Pagination and errors

Page through list endpoints and handle error responses, status codes and retries correctly.

List endpoints in the Orchestrator API are paged on the server, and every error comes back in one predictable format. This page explains both, so your integration can read large lists efficiently and react to failures correctly.

Paging through lists#

List endpoints take two query parameters:

Parameter Meaning Default Limits
page The page number, starting at 1 1 1 or more
pageSize Items per page 50 at most 100

A request with page below 1 or pageSize outside 1 to 100 is rejected with 400 Bad Request.

The response wraps the items with the paging information. The operational lists (jobs, webhooks and similar) use this shape:

GET .../jobs?page=2&pageSize=25JSONCopy
{
  "items": [ { "id": "3d1f8a44-...", "status": "Succeeded" } ],
  "page": 2,
  "pageSize": 25,
  "totalCount": 812
}

Some administrative lists (for example groups) use the generic envelope, where the count is named total:

JSONCopy
{ "items": [ ... ], "total": 14, "page": 1, "pageSize": 50 }

Read whichever count field is present. To fetch everything, keep requesting the next page until you have collected totalCount (or total) items or a page comes back empty.

page_through.pyPythonCopy
import httpx

def all_jobs(client: httpx.Client, tenant: str, workspace: str):
    page = 1
    while True:
        response = client.get(
            f"/api/v1/tenants/{tenant}/workspaces/{workspace}/jobs",
            params={"page": page, "pageSize": 100, "status": "Failed"},
        )
        response.raise_for_status()
        body = response.json()
        yield from body["items"]
        if page * body["pageSize"] >= body["totalCount"] or not body["items"]:
            break
        page += 1

Filter and sort on the server#

Filtering and sorting belong in the query, not in your client. The jobs list, for example, accepts status (repeatable), automationId, runnerId, source, createdFrom, createdTo, faultCode, q, sort and dir. The jobs table grows fast, so filtering a single page you already downloaded does not give you a real search.

Newest first

Jobs are returned newest first by default. When you page through a list that is still changing, new items can shift the pages. Narrow the query with createdTo to get a stable window.

Error format#

Errors use RFC 9457 problem details with the media type application/problem+json:

422 Unprocessable EntityJSONCopy
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.21",
  "title": "Invalid job inputs",
  "status": 422,
  "detail": "...",
  "code": "validation",
  "correlationId": "0HN6J8F1A2B3C:00000004",
  "errors": {
    "/invoiceNumber": ["..."]
  }
}
  • status repeats the HTTP status code.
  • code is a stable, machine-readable reason, such as validation, not_found, permission_required, no_capable_runner or package_version_exists. Every problem response has one.
  • title and detail explain the problem in words.
  • errors, when present, maps a field name or JSON Pointer to the messages about it.
  • correlationId identifies the request in the Orchestrator's logs.
  • Some responses add more fields, for example requiredPermission and scope on a 403, requiredRuntimes on no_capable_runner, or velophexCode with a catalog code (see below).

Every response, successful or not, also carries an X-Correlation-ID header. Log it with every failure. An administrator can search the Orchestrator log for that value to see exactly what happened.

The message wording above is illustrative. Code against status and code, not the text.

Status codes you should handle#

Status Meaning What to do
400 Bad Request The request is malformed or a value is out of range (validation) Fix the request; do not retry unchanged
401 Unauthorized No credential, or it is invalid, expired or revoked (unauthenticated) Renew the token
403 Forbidden You can see the tenant or workspace but lack the permission (permission_required), or the product is not enabled for the tenant (service_disabled) Ask for the permission named in requiredPermission
404 Not Found The resource does not exist, or you have no access to the tenant or workspace in the URL (not_found) Check the ids and your access
409 Conflict The request conflicts with current state Read code and detail; see below
413 Payload Too Large The request body is over the limit, for example a package over the upload limit (payload_too_large) Send less
422 Unprocessable Entity The request is well formed but its content is invalid, for example job inputs that do not match the entry point's JSON Schema Fix the content using errors
429 Too Many Requests A rate limit was hit Wait for Retry-After, then retry with backoff
500, 502, 503 Server or infrastructure problem (server_error) Retry with backoff; report with the correlation id if it persists

Common conflicts#

code Meaning What to do
no_capable_runner No Robot serving the workspace (or the Robot you pinned) reports the runtime the package needs. requiredRuntimes lists them. Install the runtime on a machine assigned to the workspace. See Machines and robots.
package_version_exists The package version is already published with different content Publish under a new version
package_binary_duplicate These exact package bytes are already published; the response carries their sha256 Nothing; a publisher may treat this as success
package_not_runnable The package is a workflow library, which cannot be a process Create the process from an automation package
unresolved_dependency An automation the package invokes as a step has no active version in the declared range Publish or reactivate a matching version
duplicate_reference A queue item with this reference already exists in a queue that enforces unique references. A batch with one duplicate is rejected whole. Use a new reference, or skip the item
concurrency The record changed since you read it Read it again and reapply your change
conflict Another state conflict, or an Idempotency-Key problem (see below) Read detail

Error catalog codes#

Robot, identity, package and some API errors also carry a stable code from the platform error catalog, in the form VEL-<AREA>-<STATUS>-<NNN>. In API responses it appears as velophexCode. For example:

Code Meaning
VEL-AUTH-403-001 The enrollment key has already been redeemed
VEL-AUTH-403-002 The enrollment key has expired
VEL-AUTH-403-003 The enrollment key was issued to a different host
VEL-AUTH-403-004 The machine is disabled or revoked
VEL-AUTH-408-001 Sign-in was not completed in time
VEL-AUTH-409-001 The machine's clock is too far from the server's
VEL-ROBOT-403-001 The Robot was revoked
VEL-ROBOT-409-005 The lease has expired
VEL-ROBOT-426-001 The Robot is too old for this Orchestrator
VEL-PKG-403-001 The package is not signed by a trusted signer
VEL-PKG-422-002 The package was built under a looser expression policy than the tenant's
VEL-API-409-001 The Idempotency-Key was reused with a different request, or the first request is still running

The same catalog is used by the .NET, TypeScript and Python components, so a code in a Robot log means the same thing as in an Orchestrator response. See Common issues for fixes.

Retrying safely#

  • Retry only on 429, 5xx and network failures, with exponential backoff and jitter.
  • Never retry 400, 401, 403, 404 or 422 unchanged.
  • Send an Idempotency-Key header (up to 100 characters) with a value unique to the business event on any POST, PUT, PATCH or DELETE. A retry with the same key and body gets the original answer instead of acting twice. For a job start, that is the existing job with 200 OK instead of a second job with 201 Created.
  • The same key with a different body, or while the first request is still running, is refused with 409 (VEL-API-409-001). Use a new key for a new request.
  • Keys are scoped to the tenant and the caller, so two integrations cannot collide on the same key.
HTTPCopy
POST /api/v1/tenants/{tenantId}/workspaces/{workspaceId}/jobs HTTP/1.1
Authorization: Bearer vpx_pat_...
Idempotency-Key: invoice-2026-00042
Content-Type: application/json

{ "automationId": "5c0e9d1a-...", "inputs": { "invoiceNumber": "00042" } }

Next steps#

Paging through lists

Filter and sort on the server

Error format

Status codes you should handle

Common conflicts

Error catalog codes

Retrying safely

Next steps