Error Codes

All API errors follow a consistent JSON structure with a machine-readable code and a request_id for support.

{
  "error": {
    "message": "Human-readable error description",
    "code": "machine_readable_error_code",
    "details": {}
  },
  "request_id": "uuid-v4-request-identifier"
}

Response headers: X-Request-ID carries the same value as request_id for server-side log correlation. Fields:

error.message (string, required) — Human-readable error description
error.code (string, optional) — Machine-readable error code for programmatic handling
error.details (any, optional) — Additional context (e.g., validation errors)
request_id (string, optional) — Unique request identifier for debugging

HTTP status codes

Status	Description	Usage
`200 OK`	Successful request	Most `GET`, `PATCH`, `DELETE` operations
`201 Created`	Resource created	`POST` operations that create new resources
`400 Bad Request`	Invalid request parameters	Malformed DSL, invalid query parameters, bad execution references
`401 Unauthorized`	Authentication required or failed	Missing/invalid bearer token, expired token, user not found
`404 Not Found`	Resource does not exist	Flow or execution ID not found, entity not in database
`409 Conflict`	Resource already exists	Duplicate flow name, duplicate execution ID, constraint violation, an `Idempotency-Key` already used on a run you can’t access
`422 Unprocessable Entity`	Validation error	Request body or a parameter (e.g. a malformed `Idempotency-Key` header) fails validation, type errors, constraint violations
`500 Internal Server Error`	Unexpected server error	Database errors, repository errors, unhandled exceptions

Error code catalog

`validation_error`

HTTP 422. Request body or parameters failed validation. Review the details array, which lists each invalid field:

{
  "error": {
    "message": "Request validation failed",
    "code": "validation_error",
    "details": [
      {
        "type": "missing",
        "loc": ["body", "display_name"],
        "msg": "Field required",
        "input": {}
      }
    ]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Each details item contains: type (error type), loc (JSON path to the field), msg (message), input (the invalid value), and optional ctx (constraints) and url. A malformed Idempotency-Key header on POST /api/flow-executions (not a ULID, or lower case) is reported the same way, and no run is created:

{
  "error": {
    "message": "Request validation failed",
    "code": "validation_error",
    "details": [
      {
        "type": "ulid_format",
        "loc": ["header", "Idempotency-Key"],
        "msg": "Unrecognized format"
      }
    ]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

`invalid_dsl_input`

HTTP 400. The flow DSL definition is malformed or invalid — missing required fields, invalid task executor names, circular dependencies, or configurations that don’t match executor schemas.

{
  "error": {
    "message": "Flow definition validation failed: tasks must be an array",
    "code": "invalid_dsl_input",
    "details": [
      "definition.tasks: Expected array but got object",
      "definition.version: Must be a positive integer"
    ]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Ensure all tasks reference valid executors and that dependencies form a valid directed acyclic graph (DAG).

`not_found`

HTTP 404. The requested resource does not exist — wrong ID, deleted resource, or a resource owned by a different organization (and therefore not visible).

{
  "error": {
    "message": "Flow not found with id: 550e8400-e29b-41d4-a716-446655440000",
    "code": "not_found"
  },
  "request_id": "660e8400-e29b-41d4-a716-446655440000"
}

`conflict`

HTTP 409. The request conflicts with existing state or a database constraint — for example, a duplicate flow name within an organization. Use a different identifier, or retry with backoff for concurrent-modification conflicts. On POST /api/flow-executions, a 409 means a run of this flow with the same Idempotency-Key exists but is not accessible to you (for example, your access to the flow changed while the request was in progress). No new run is created. Repeating the request with the same key won’t create one either; use a new key only if you want a new run.

{
  "error": {
    "message": "An execution of flow 550e8400-e29b-41d4-a716-446655440000 with Idempotency-Key 01ARZ3NDEKTSV4RRFFQ69G5FAV exists but is not accessible",
    "code": "conflict"
  },
  "request_id": "660e8400-e29b-41d4-a716-446655440000"
}

`bad_request`

HTTP 400. The request is syntactically correct but semantically invalid — invalid query parameter values, references to non-existent resources, or invalid state transitions.

{
  "error": {
    "message": "Can't find execution referenced in query parameter 'start_from_execution_id'",
    "code": "bad_request"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

`user_info_not_found`

HTTP 401. User information could not be retrieved from the authentication token — invalid/expired token or a deactivated account. Re-authenticate to obtain a fresh token.

`repository_error`

HTTP 500. A database or repository-layer error occurred (connection failure, query timeout, deadlock). Retry with exponential backoff; contact support with the request_id if it persists.

`service_error`

HTTP 500 (or a custom status). An application service-layer error — business-logic failure, external integration failure, or unexpected state. Check the message for specifics.

`internal_error`

HTTP 500. An unexpected internal error. These are automatically logged with full stack traces. Retry (it may be transient) and report the request_id.

HTTP errors without a code

Some errors return a status code without an error.code field — for example 405 Method Not Allowed, 415 Unsupported Media Type, 413 Request Entity Too Large, or 429 Too Many Requests. Handle these by HTTP status.

Handling errors

Check the HTTP status code first

if response.status_code >= 400:
    error = response.json().get("error", {})
    code, message = error.get("code"), error.get("message")

Branch on the error code

if code == "not_found":
    return None
elif code == "validation_error":
    display_validation_errors(response.json()["error"]["details"])
elif code == "user_info_not_found":
    redirect_to_login()

Retry transient server errors

RETRYABLE = {"repository_error", "service_error", "internal_error"}
if code in RETRYABLE:
    retry_with_backoff(request)

Retrying POST /api/flow-executions after a timeout, connection error or 5xx is only safe when the request carries an Idempotency-Key, and the retry reuses the same key. Without one, the first request may already have started the run, and the retry starts a second one. See Retry safely.

Log the request_id for support

request_id = response.json().get("request_id") or response.headers.get("X-Request-ID")
logger.error(f"API error: {message} (request_id: {request_id})")

Summary

Error code	HTTP status	Category	Retryable
`validation_error`	422	Client	No — fix request
`invalid_dsl_input`	400	Client	No — fix DSL
`not_found`	404	Client	No — resource doesn’t exist
`conflict`	409	Client	No — resource conflict
`bad_request`	400	Client	No — fix request
`user_info_not_found`	401	Auth	No — re-authenticate
`repository_error`	500	Server	Yes — retry (starting a run: only with the same `Idempotency-Key`)
`service_error`	500	Server	Yes — retry (starting a run: only with the same `Idempotency-Key`)
`internal_error`	500	Server	Yes — retry and report (starting a run: only with the same `Idempotency-Key`)
(no code)	4xx/5xx	HTTP	Depends on status

Overview

Endpoints

HTTP status codes

Error code catalog

`validation_error`

`invalid_dsl_input`

`not_found`

`conflict`

`bad_request`

`user_info_not_found`

`repository_error`

`service_error`

`internal_error`

HTTP errors without a code

Handling errors

Summary

​HTTP status codes

​Error code catalog

​validation_error

​invalid_dsl_input

​not_found

​conflict

​bad_request

​user_info_not_found

​repository_error

​service_error

​internal_error

​HTTP errors without a code

​Handling errors

​Summary

HTTP status codes

Error code catalog

`validation_error`

`invalid_dsl_input`

`not_found`

`conflict`

`bad_request`

`user_info_not_found`

`repository_error`

`service_error`

`internal_error`

HTTP errors without a code

Handling errors

Summary