## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://docs.flows.super.ai/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

| 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 |
| `422 Unprocessable Entity` | Validation error | Request body 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`.

### `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

| 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 |
| `service_error` | 500 | Server | Yes — retry |
| `internal_error` | 500 | Server | Yes — retry and report |
| _(no code)_ | 4xx/5xx | HTTP | Depends on status |