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:
{ "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.
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:
{
"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": ["..."]
}
}
statusrepeats the HTTP status code.codeis a stable, machine-readable reason, such asvalidation,not_found,permission_required,no_capable_runnerorpackage_version_exists. Every problem response has one.titleanddetailexplain the problem in words.errors, when present, maps a field name or JSON Pointer to the messages about it.correlationIdidentifies the request in the Orchestrator's logs.- Some responses add more fields, for example
requiredPermissionandscopeon a403,requiredRuntimesonno_capable_runner, orvelophexCodewith 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,5xxand network failures, with exponential backoff and jitter. - Never retry
400,401,403,404or422unchanged. - Send an
Idempotency-Keyheader (up to 100 characters) with a value unique to the business event on anyPOST,PUT,PATCHorDELETE. 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 with200 OKinstead of a second job with201 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.
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