Error Codes - SuperAI Flows

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

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

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.

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.

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

1 Check the HTTP status code first

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

2 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()

3 Retry transient server errors

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

4 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